Notation conventions for methods

The following conventions are used in the method descriptions in this Wiki. They apply fully, and primarily, to the methods associated with Janus SOAP classes and other classes documented in the Janus SOAP Reference Manual.

• Symbols used in the syntax include the following. Usually, they represent method objects; in actual code, they may be replaced by object variables of the indicated class or by method invocations that return such object variables:

• • nr -- Denotes an abstract class (short for "node reference") for methods that operate on a node and that can be used with either an XmlNode or an XmlDoc. If an XmlDoc, the node for the operation is the root node.
  • doc -- Denotes an object of class XmlDoc.
  • nod -- Denotes an object of class XmlNode.
  • nlis -- Denotes an object of class XmlNodelist.

• Although the terms "XmlNode" and "node" are closely related, effort is made to distinguish them as necessary in the method descriptions. An XmlNode is an object that points to a node in an XmlDoc tree. Similarly, an "XmlNodelist" is an object that contains a set, or list, of XmlNodes selected from a particular XmlDoc. Strictly speaking, a "nodelist" does not exist, but the term is occasionally used as an abbreviation or generalization of XmlNodelist.

• Null objects, null strings, empty results

• • A "Null" object is one that has been deleted or that has not been instantiated. A "null" string is a zero length string value. The text in the method descriptions distinguishes these two terms.

• • Object-type arguments must not be Null, unless that argument explicitly allows Nulls. Hence, a Null argument typically causes a request cancellation. Currently, no methods described in this chapter allow Null object arguments, and the "Request Cancellation Errors" section for each method does not include this condition.

• • Some methods that have an XPath argument allow the result of the XPath expression to be the empty set of nodes; most, however, will cancel the request if this happens. Each method that has an XPath argument will either list the empty XPath result as a request cancellation error, or will explain the operation of the method when the XPath result is the empty nodeSet.

Notation conventions for object methods

These conventions apply primarily to the syntax for method invocation and the argument descriptions in the reference sections for individual class methods.

• 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.

• 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 with the word "optional."

• 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:

• • methodname( argName = argValue )

Whether an argument name is a "named parameter" is declared for the method within the class definition with the NameAllowed or NameRequired keyword.

• Many functions that return a result may also be invoked by using "Call." The descriptions of such functions say that they are "callable" and display a bracketed %variable and equality sign in syntax (for example, [%name = ]). For Subroutines, which are always callable, the Call keyword is optional.

• Methods are non-shared unless otherwise identified. A shared method is recognizable by the %(classname): notation preceding the method name in the method syntax, which implies that the method need not operate on a particular object. Using the class name in this way denotes that the method is shared, and it models one way you can invoke the method. You can also invoke shared methods using the %objectVariable: notation used by non-shared, or instance, methods. In this case, %objectVariable is used to identify the class to which the method belongs, not that the method operates on %objectVariable (note that %objectVariable may be null for a shared method invocation).

• Italicized arguments are placeholders: you must substitute an actual value.