PC Online 1997 May

home *** CD-ROM | disk | FTP | other *** search

/ PC Online 1997 May / PCO_5_97.ISO / FilesBBS / OS2 / NETREXX.ARJ / NETREXX.ZIP / NetRexx / netrexx.doc < prev next >

Wrap

Text File | 1997-01-02 | 57.1 KB | 1,487 lines

NetRexx 1.00 NetRexx language summary and quick reference ============================================ Copyright(c) IBM Corporation, 1996, 1997. All rights reserved. Introduction """""""""""" NetRexx is a new programming language derived from both Rexx and Java(tm); the rules of syntax closely follow those of Rexx, while the semantics often follow Java. It is a dialect of Rexx that can be as efficient and portable as Java, while preserving the low threshold to learning of the original Rexx language. Further, the language is intended to be even more keyword safe than Rexx: it should be possible to re-compile or execute an existing NetRexx program _from source_ at any time without additions to the keywords known to the language invalidating an existing program. Like Rexx, NetRexx is designed to allow clear separation of its concepts, so it may be introduced gradually. Also like Rexx, sensible defaults are defined to aid ease of use -- especially for the novice programmer. These defaults can be turned off for the programmer who needs stricter type-checking than Java, or other extra checks. The Java virtual machine environment is assumed to be a platform for NetRexx, and this places some constraints on the NetRexx language. For example, the semantics of type resolution are in part determined by the environment, not the language. The constraints of efficiency, safety, and environment implied that this language would have to differ in some details of syntax and semantics from Rexx; it could not be a fully upwards-compatible extension to Rexx. The need for change, however, has offered the opportunity to make some important simplifications and enhancements to the language to strengthen the original Rexx design, and incorporate other additions from ANSI Rexx, Object Rexx, and Java. The most up-to-date information on NetRexx and Rexx may be found at: http://www2.hursley.ibm.com Mike Cowlishaw, IBM Fellow IBM UK Laboratories Language Description """""""""""""""""""" The following sections describe the various aspects of the NetRexx language. This summary is intended as a handy reference and is not intended to be a rigorous definition. It assumes knowledge of Rexx (and a little of Java semantics). Please see the _NetRexx Language Definition_ at http://www2.hursley.ibm.com/nrl/ for full details of the language. Base syntax """"""""""" Tokenization of NetRexx programs into clauses is the same as Rexx (blanks adjacent to special characters disappear, strings can be delimited with single or double quotes, "/*" comments nest, etc.) with the following differences: o The sequence '--' (outside a literal string or comment) introduces a comment that is terminated by end-of-line, for example: Say 'Hello World!' -- displays a message Similarly, the sequences '++' and '\\' are reserved for future use (they are in error, rather than some combination of operators). o Only '\' is allowed for the 'not' operator. o A number in exponential notation must have a sign after the 'E'. The following are valid: 12E+2 12e-3 12.7E+0 1E-1 /* 1e6 is not a valid number */ A symbol that starts with a digit must have the syntax of a number. At present, numbers cannot start with a period. o A comment is always equivalent to a blank (it does not act as a transparent separator). o A hyphen (minus sign) is used for continuation rather than comma. o Square brackets are used for array/stem notation, as in Object Rexx (and other languages). o '?', '!', and '.' are not permitted in identifiers (names). o C-like character encodings are allowed in literal strings, introduced by backslash. Specifically the following are allowed: \t \n \r \f \" \' \\ \- \0 \xhh \uhhhh meaning tab, newline (linefeed), carriage return, form feed, double quote, single quote, backslash, delete, zero-character, hexadecimal, unicode. In the last two, two or four hexadecimal digits, respectively, are required. The 'zero character' can therefore also be written as \x00 or \u0000. The escape letters (t, n, etc.) and the hexadecimal digits may be in lower or upper case. Rexx-style quote-doubling is also accepted. o A source-level unicode escape is under consideration (currently a notation using braces is favoured -- braces, outside literals, could wrap sections of code -- or the whole program -- where unicode escapes are permitted; a unicode escape might then look like {0012 0321}, and so on (with optional whitespace at four-character boundaries). Expressions and operators """"""""""""""""""""""""" NetRexx expressions follow the rules of Rexx. All Rexx operators are valid syntax, with Rexx precedence rules during evaluation. Parentheses can be used, as usual, to alter operator precedence by defining sub-expressions. The semantics of operators may vary as there is more than one data type and operators can be overloaded (as an implementation detail rather than a language feature) in NetRexx. More specifically, in the case of the 'Rexx' string class provided by NetRexx, the Rexx operators act as defined by the ANSI standard for Rexx (with the single exception that non-strict comparisons are case-independent). For other classes (the binary 'int' type provided by Java, for example) traditional binary arithmetic rules apply. Terms (the data descriptors in expressions) may be a sub-expression (an expression enclosed in parentheses) or one of the following: --- Literals --- Literals are used to express character strings and numbers: literal strings e.g., "don't" 'Hello' 'x:' "\x00" numbers e.g., 1 12 12.4 1e-4 1.066E+3 --- References --- References are terms that refer to variables (local variables within methods, arguments to methods, or properties), methods, arrays, or classes: simple symbols e.g., Fred I J method calls e.g., Start(x,y) Stop() array references e.g., Dallas[rev] Pooks[12,10] types (classes) e.g., Rexx, java.lang.String, int Blanks are not permitted between the name of a method and the '(', or between the name of an array reference and the '['. Simple symbols found in a program can refer to a property in the current class, a local variable, a method in the current class (if it takes no arguments and is not a constructor), a keyword, or a type (class). --- Compound references --- The various forms of reference may be combined together with the '.' connector to form compound references. Syntactically, any combination is valid, though some may be invalid semantically. The following are examples of syntactically valid compound references: myaddress.street list[3].length is.openstream Rexx.x2c('fade') "abc".pos('b') In general, the semantics of a compound reference follow the rules of Java. A compound reference must start with a string, a sub-expression, a reference or a type, where the type may be qualified (include a package name). Each piece after the next connector can further refine the term, returning a reference or (optionally, if it is the final part of a term) a value. The end result of a term is therefore either a type, a typed object reference, or a typed value. Blanks are not permitted adjacent to connectors. The parentheses indicating a method call may be omitted in compound references if the method takes no arguments and is not a constructor (optionally, they can be made to be required, using OPTIONS STRICTARGS). Types and Variables """"""""""""""""""" NetRexx variables all follow the same syntax rules, but are used in different contexts. These are: o Properties: variables that are associated with a class or an instance of a class (an object). When an object is constructed, its properties are created and are usually initialized to some value. Properties may be STATIC, which means that they are associated with a class and are initialized when the class is first loaded, or CONSTANT, which means that they are static and do not change after initialization. o Method arguments: when a method is invoked, arguments may be passed to it. These arguments are assigned to variables for use within the method. Often, these arguments will be references to objects known to the caller. o Local variables: variables that are local to a method; each time a method is invoked a distinct set of local variables is used (as when using the PROCEDURE instruction in Rexx). NetRexx includes the concept of types (classes), though substantial programs and applets can be written without introducing explicit type declarations. The type of a NetRexx variable is determined by the type of the value of the expression that is first assigned to it ('first' is determined statically by position in a program rather than dynamically). For subsequent assignments, it is an error to assign a value to a variable with a type mismatch unless the language processor can determine that the value can be assigned safely. In practice, this means that the types must match exactly, or they must be a 'well-known' type such as Rexx, String, int, (etc.) for which safe conversions are defined. An object can also always be assigned to a type which is a superclass of the object's type. Optionally, a stricter rule for assignment (where the types must be identical) may be applied, using OPTIONS STRICTASSIGN. Objects in NetRexx are created by calling a 'constructor method' which has the same name as the class. The syntax for calling a constructor method is essentially the same as a function call in Rexx and other languages. For example, if there are classes called 'ibm.util.hex', 'RunKnown', and 'Window': hexy=ibm.util.hex(3) -- 'hexy' has type 'ibm.util.hex' rk=RunKnown() -- 'rk' has type 'RunKnown' fred=Window(10, 20) -- 'fred' has type 'Window' s="Hello world" -- 's' has type 'Rexx' j=5 -- 'j' has type 'Rexx', as if written j="5" The last two examples above illustrate that, by default, the types of literal strings and numbers are Rexx and so variables tend to be of a Rexx type. This allows the language to remain simple and easy to learn, as many useful programs can be written solely using the Rexx type. Potentially more efficient (though of course less human-oriented) binary representations of literals can optionally be selected to be the default by using OPTIONS BINARY. In this case, in a Java environment, the types of 's' and 'j' above would have been 'java.lang.String' and 'int' respectively. A variable may be introduced ('declared') without giving it an initial value by simply assigning a type to it: i=int j=Window The type of a value may be overridden (if required) by 'conversions' (sometimes called 'casting'). This syntax for a conversion is the same as the Rexx "blank operator": when the left-hand-side of a blank operator is a type (class name, perhaps with dimensions) then the operation assigns a type to the right-hand-side term of the operator. For example: int 7.0 int 7.3**5 Exception e Complex vector The priority (precedence) of the conversion operator is the same as when it means concatenate-with-blank; it is lower than arithmetic operators but higher than logical operators. You can test whether the type of a given object can be converted to another type using the '<=' (or '>=') operators. For example: if i<=Object then say 'I is an instance of Object' if String>=i then say 'I is an instance of String' This also works for testing whether one type is the subclass (or the same as) another: if String<=Object then say 'String is an Object' If the conversion is known to be impossible at 'compile time', then an error will be reported at that time. Certain types (such as 'int' in the examples above) may be defined as 'primitive' by the underlying environment, and this may affect their semantics (objects of a primitive type may be passed by value rather than by reference, for example). However, NetRexx makes no distinction of syntax for primitive types. An implementation of NetRexx can determine automatically from knowledge of primitive types (and other factors) when an object is being constructed, so there is no 'new' operator. As in Rexx, both storage allocation and storage reclamation are automatic. --- The scope of variables --- In order for types to be determined and type-checking to be possible at 'compile-time', and easily determined by inspection, variable typing is static in scope: o Within a class, properties have unique names (they cannot be overridden by method arguments or by local variables within methods); this avoids error-prone ambiguity. The type of a property is determined from the expression (which may be just a type) that is assigned to it. Properties can only be introduced before the first method in a class. o Within a method, a method argument acts like a local variable (that is, it is in the same name space as local variables); it can be considered to be a local variable that is assigned a value just before the body of the method is executed. o Within methods, variables can take only one type, the type assigned to them when first encountered in the method (in a strict 'physical' sense, that is, as parsed from top to bottom). Since methods tend to be small, there is no local scoping of variables inside the blocks within a method. Thus, unlike in Java, in this example: method iszero(x) if x=0 then qualifier='is zero' else qualifier='is not zero' say 'The argument' qualifier'.' the variable "qualifier" is known throughout the method and has a value when the SAY instruction is executed. Within a NetRexx program, variable names are caseless (for example, the names 'Fred' and 'FRED' refer to the same variable). Where public names are exposed (for example the names of properties, classes, and methods, and in cross-reference listings) the case used for the name will be that used when the name was first introduced. Type checking and method resolution """"""""""""""""""""""""""""""""""" As outlined above, type checking in NetRexx is generally more relaxed than in Java (String and Rexx classes may be freely inter-assigned, for example), following the principle that assignments that do not lose information from data should normally be allowed. Permitted assignments are detailed later in this section. For some applications, a discipline of strict type checking may be an advantage, and for these, NetRexx provides the STRICTASSIGN option. This strict checking is stronger than in Java, in that types much match exactly. The type checking (normal or strict) is also carried over into method resolution (determining which method in a class best fits a given method invocation). In summary, this works as follows: 1. The class of the object on which the method is being invoked is determined. 2. Candidate methods in the class are selected. They must have the the same name and the same number of arguments as the method invocation, and it must be possible to assign the result of each argument expression to the corresponding argument in the method description (if strict assignment checking is in effect, the types must match exactly). 3. If there are no candidate methods then the superclass of the current class is chosen and step 2 is repeated. If there is no superclass (that is, all superclasses have been tried), an error is reported. 4. If there is just one candidate method, that method is used; the search is complete. Note that in this case superclasses of the current class are not searched for methods, even though a lower-cost method may exist at a higher level. 5. If there is more than one candidate method, the 'cost' of the assignments from expressions to arguments is computed for each method (see below). If one has a lower cost than all others, that method is used and the search is complete. If there are two or more with the same minimum cost, and 'ambiguous method invocation' error is reported. --- Cost of a method invocation --- The cost of a method invocation is the sum of the costs of the assignments from each invocation argument expression to the corresponding method arguments. The cost of an assignment is 0 if the types match exactly, 1 if the assignment can be made without invoking a conversion method, but the types do not match exactly (for example assigning an 'int' to a 'long'), and 2 if an assignment would require the invocation of a conversion method (for example, assigning an 'int' to a 'Rexx' string). More generally, NetRexx 'costs' conversions of all types, where applicable, and may use those costings in other conversion situations. Further tuning of the costing algorithms can be expected. --- Permitted assignments (automatic conversions) --- Unless OPTIONS STRICTASSIGN is in effect, the following assignments are permitted (this list may be expanded in the future): String -> Rexx, char[], or char char[] -> Rexx, String, or char char -> Rexx, String, or char[] Rexx -> primitive, char[], String, or char primitive -> Rexx, String, char[], or char primitive -> primitive (if no loss of information can take place) Any type -> exactly matching type Any type -> superclass of type (or an interface implemented by the type or a superclass) null -> any non-primitive In the above: o 'String' is the class java.lang.String o 'char' is a primitive type, treated as a one-character string o 'Rexx' is the class netrexx.lang.Rexx o 'primitive' means any of the Java primitive binary types (int, char, long, etc.) o 'null' is a null reference; assigning it to a variable is equivalent to making the variable uninitialized. Some of the conversions can cause a run-time error (exception), as when a Rexx string contains a number that is too large for an int and a Rexx to int conversion is attempted. The boolean primitive is treated as in Rexx: a boolean is a number that may only take the values 0 or 1. A boolean may therefore be assigned to any primitive type, as well as to String or Rexx. --- Case of method, property, and class names --- In NetRexx, the lookup of public names will be both case-preserving and caseless. If a class or method is referenced by the name 'Foo', for example, an exact-case match will first be tried at each point that a search is made. If this succeeds, the search is complete. If it is does not succeed, a caseless search in the same context is carried out, and if one item is found, then the search is complete. If more than one item matches then an 'ambiguous reference' error is reported. At present, lookup of external names is case-sensitive; when this restriction is lifted, for applications that require exceptional robustness, OPTIONS STRICTCASE may be specified to require that all name matches are exact (case-sensitive). Methods and constructors """""""""""""""""""""""" Methods all follow the same syntax rules (see the description of the METHOD instruction, elsewhere), and are usually invoked in context of an existing object. A special kind of method, called a constructor method, is used to actually create an object. Constructor methods always have the same name as the class in which they are found, and construct an object of that class. There will always be at least one constructor if objects are to be created (NetRexx will add a default constructor that takes no arguments if none are provided). All constructors follow the following rules: 1. Constructors must call a constructor of their superclass before they carry out any initialization of their own (this is so any initialization carried out by the superclass takes place at the appropriate moment). Therefore the first instruction in a constructor must be either a call to super() (with optional arguments), or a call to this() (with optional arguments). In the latter case, another constructor in the same class is called; eventually one that explicitly calls super() will be invoked and the chain of local constructor calls ends. As a convenience, NetRexx will add a default call to super() if the first instruction in a constructor is not a call to this() or super(). 2. By definition, constructors create an object of the current class and return it. Therefore, the RETURNS keyword on the method instruction is optional (if specified, the RETURNS type must match the class), and the only possible forms of the RETURN instruction on a constructor are either 'return this' or 'return' -- in the latter case, the 'this' is assumed (this form will be assumed at the end of a method, as usual, if necessary). Here is an example of a class with two constructors, showing the use of this() and super(), and taking advantage of the assumptions: class MyChars properties private value=char[] -- the data 'in' the object method MyChars(c=char[]) -- construct the object from a char array super() -- initialize superclass (in this case Object) value=c -- record the value (without copying) method MyChars(s=String) -- construct the object from a String this(s.toCharArray()) -- convert to char[] and use the above Objects of type 'MyChars' could then be created thus: myvar=MyChars("From a string") or by using an argument that has type char[]. Note that all references to constructors must be identified by the use of parentheses, to distinguish them from references to the type (class) of the same name. Special names and methods """"""""""""""""""""""""" For convenience, NetRexx provides some special names for naming commonly-used concepts within terms. These are only recognized if there is no variable of the same name previously seen in the current scope (this allows the set of special words to be expanded in the future, if necessary, without invalidating existing variables). These names are not reserved; they may be used as variable names instead, if desired. There are also two 'special methods' that are used when constructing objects, and constructors for the primitive types. --- Special names --- The following special names are allowed in NetRexx programs. o ask -- returns a Rexx string, read from the standard input stream (usually the user's "console"). For example: if ask='yes' then say 'OK' In the Java environment, ask is simply a shorthand for 'RexxIO.Ask()'. o digits -- the current setting of numeric digits, returned as a Rexx string. o form -- the current setting of numeric form, returned as a Rexx string. o length -- represents the length of an array. For example: foo=char[7] say foo.length /* would say '7' */ Note that you can get the length of a String or Rexx object with the same syntax (unless OPTIONS STRICTARGS is in effect). In these cases, however, a length() method is being invoked. o null -- the 'empty reference'. This represents "no value" and may be assigned to variables that refer to classes, or may be used in a comparison for equality (or inequality). For example: blob=int[3] /* 'blob' refers to an array of 3 ints */ blob=null /* 'blob' is still of type int[], but refers to no real object */ The 'null' value may be considered to represent the state of being uninitialized. That is, the state of a variable after DROP in Rexx. o source -- returns a Rexx string identifying the source of the current class. The first two words of the string are 'Java method', identifying the environment, and the third is the name of the sourcefile (e.g., 'Fred.nrx'). If 'options binary' is in effect, a java.lang.String is returned. o super -- refers to the current object, except that a search for methods or properties which it qualifies will start from the superclass rather than in the current class. This is used for invoking a method or property (in the superclass or one of its superclasses) that has been overridden in the current class. For example: method printit(x) say 'it' -- modification super.printit(x) -- and now the usual processing super can only appear as the first item in a compound reference term. o this -- refers to the current object. When a method is invoked, for example in: word="hello" /* 'word' now refers to "hello" */ say word.substr(3) /* invokes substr method on "hello" */ then the method 'substr' in class Rexx is started, with argument '3', and with the properties of the object "hello" available to it. These may be accessed simply by name, or (more explicitly) by prefixing the name with 'this.'. Using 'this.' often makes a method more readable, especially when several objects of the same type are being manipulated in a method. If a property being referenced is in fact owned by a superclass of the current class, then then prefix 'this.' is the simplest way to indicate that name refers to a property rather than to a local variable. (You could also qualify it by 'super.', or the name of the superclass.) o trace -- the current TRACE setting o version -- returns a Rexx string identifying the version of the language processor that generated the current class. This consists of five words delimited by blanks: 1. A word describing the language. The first seven letters will be the characters 'NetRexx', and the remainder may be used to identify a particular implementation or language processor. This word may not include any periods. 2. The language level description. For example, '1.01'. 3. Three tokens describing the language processor release date in the same format as the default for the Rexx date() function. For example, '3 Jan 1997'. If 'options binary' is in effect, a java.lang.String is returned. With the exception of 'length', the special names may only be used alone or as the first item in a compound reference. --- Special methods --- Constructors (methods used for constructing objects) in NetRexx must invoke a constructor of their superclass before making any modifications to the current object (or invoke another constructor in the current class). This is simplified and made explicit by the provision of the special method names 'super' and 'this', which refer to constructors of the superclass and current class respectively. These special methods are only recognized when used as the first, method call, instruction in a constructor. See "Methods and constructors". In addition, NetRexx provides special constructors for the primitive types that allow bitwise construction of primitives. For example: i=int 77 c=char(i) -- c is now the character 'M' j=int(c) -- j is now the integer 77 Note that the conversion j=int c would have failed, as 'M' is not a number. The argument to a primitive constructor must be a primitive. Arrays """""" NetRexx includes the concept of arrays (ordered references to objects of the same type, indexed by integers). In the Java environment, arrays are constrained to be fixed size, and are indexed by integers with the first item in the array having the index 0. Individual objects of class Rexx also support an associative array lookup mechanism (where the index is not constrained to be just integers), equivalent to Rexx stems; this is described in the next section. Arrays are indicated in NetRexx syntax by the use of square brackets, [], and are constructed just like other objects except that brackets are used instead of parentheses: arg=String[4] -- makes an array of four Strings i=int[3] -- makes an array of three 'int's Brackets are used conventionally for referring to a member of an array: i[2]=3 -- sets the '2'-indexed value of 'i' j=i[2] -- sets 'j' to the '2'-indexed value of 'i' Regular multiple-dimensioned arrays may be constructed and referenced by using multiple expressions within the brackets, separated by commas: i=int[2,3] -- makes a 2x3 array of 'int' type objects i[2,2]=3 -- sets the '2,2'-indexed value of 'i' j=i[2,2] -- sets 'j' to the '2,2'-indexed value of 'i' The type of a variable that refers to an array can be set (declared) by assignment of the type with array notation that indicates the dimension of an array without an initial size or sizes: k=int[] -- one-dimensional array of 'int' objects m=float[,,] -- three-dimensional array of 'float' objects The same syntax is also used when describing an array type in the arguments of a METHOD instruction or when converting types. Indexed variables """"""""""""""""" All objects of class Rexx which are not fixed-dimension arrays support an associative array lookup mechanism (where the index is not constrained to be just integers), equivalent to stems in Rexx. The syntax is the same as for arrays, with one or more index expressions separated by commas within the square brackets. Each index must be a Rexx string (if not, it will be converted to a Rexx string). For example: surname='Unknown' -- default value surname['Fred']='Bloggs' surname['Davy']='Jones' try='Fred' say surname[try] surname['Bert'] would say "Bloggs Unknown". The indexes in the example are single words, however they may be any character string. Index strings are taken 'as-is' -- that is, they must match exactly in case and length for a reference to find a previously-set item. Before using associative array indexing on a Rexx object, the object must exist; the value of the object is used as the default value whenever an associative reference finds no explicit value. Clauses """"""" A NetRexx program is parsed into clauses (most often delimited by end-of-line, but also by semicolon and certain keywords), following Rexx rules. Recognizing that command strings to environments are now often replaced by other forms of messages, NetRexx does not assume that any clause that is an expression is a command string. This frees several combinations of syntax for other uses. Forms of clause that are currently defined are: Null clauses: any empty clause. These are ignored, as in Rexx, and can never affect the execution of a NetRexx program. Method clause: a clause with the syntax of a single term of which the last or only part resolves to a method call. Assignment: a clause consisting of a single term, followed by an '=' character and an expression. An assignment introduces a variable and sets its type if the target is a simple symbol and it is the first occurrence of that variable name in a context. Keyword instruction: a clause that is not one of the above and is introduced by a simple symbol that is a keyword known to NetRexx. The rules for keyword safety are stronger than in Rexx: a keyword (or sub-keyword) in NetRexx will only be recognized if it is not the name of a known variable. There are no label clauses (e.g., 'fred:') in NetRexx; labels for blocks are given on the instruction that starts the block. Keyword instructions """""""""""""""""""" The following short descriptions of keyword instructions show examples of syntax, not syntax rules. Keywords are indicated by upper case, though may be written in lower or mixed case. Sub-keywords may not be repeated. CATCH instruction ''''''''''''''''' Syntax: CATCH ZeroDivide CATCH zd=ZeroDivide (See 'Exceptions' section for details.) If no variable is specified, the exception will be caught but not saved for processing. The variable used in a CATCH instruction must be a simple name (not an array reference or other term), and refers to a variable or property in the current class. CLASS instruction ''''''''''''''''' Syntax: CLASS Biped CLASS blob EXTENDS Object CLASS ape EXTENDS Biped IMPLEMENTS Sitting, Standing CLASS calc EXTENDS Rexx USES Math CLASS RexxOperators INTERFACE Introduces a class. See 'Program Structure'. EXTENDS names a superclass that this class extends, the default being the top of the class hierarchy ('Object'). Class 'ape' in the example is therefore a subclass of 'Biped', which is a subclass of 'Object'. IMPLEMENTS lists one or more interface classes that this class implements (see Java documentation for a description of interfaces). The INTERFACE keyword declares a class to be an interface. USES lists one or more classes which will be searched for constants, static properties, and functions when the first part of a term is unresolved. Several other keyword options are allowed: o PUBLIC -- the class is public (visible outside the program). There must be one public class in a program; by default, the first class in a program is assumed to be PUBLIC. o PRIVATE -- the class is only visible inside this program. This is the default for the second and subsequent classes in a program. o ABSTRACT -- the class is abstract (that is, some or all of its methods have no body and must be specified by a subclass). An abstract class cannot have instances. o FINAL -- the class cannot be subclassed. DO instruction '''''''''''''' Syntax: DO DO LABEL frank DO PROTECT someobject DO ... END is the simple grouping construct. Looping forms of the DO from Rexx use the LOOP keyword in NetRexx. If a LABEL is specified on the DO, then a LEAVE which specifies that label may be used to leave the DO group, and the END that ends the block may optionally specify the label of the DO group for additional checking. For example: do label sticky ... if x then leave sticky ... end sticky If PROTECT is given it is followed by a term that must resolve to an object reference; while the DO group is being executed, the object is protected -- that is, the code in the DO group has exclusive access to the object. Both PROTECT and LABEL may be specified, if needed. CATCH and FINALLY can be used with DO (see "Exceptions" section for details). EXIT instruction '''''''''''''''' Syntax: EXIT expression As in Rexx; the expression, if present, is returned to the environment as a string. The environment may place further restrictions (such as requiring that the string be convertible to some small integer), and may provide a default. Note that EXIT is global, in that all objects and classes currently active will be lost; it should normally only be used in stand-alone applications. FINALLY instruction ''''''''''''''''''' Syntax: FINALLY (See "Exceptions" section for details.) A semicolon is assumed after FINALLY. IF instruction '''''''''''''' Syntax: IF a=b THEN i=1; ELSE i=2 As in Rexx. IMPORT instruction '''''''''''''''''' Syntax: IMPORT ibm.rexx.Rexx IMPORT ibm.rexx. Similar to Java; if the term given ends in a name, a single class is imported. If it ends in a dot, then an entire package is imported. In this latter case, full importation of sub-trees is assumed (that is, 'IMPORT ibm.' would import all subtrees of the 'ibm.' packages). In the Java environment, "import netrexx." and "import java." are assumed. IMPORT is considered to be an 'environment-dependent' instruction at present. ITERATE and LEAVE instructions '''''''''''''''''''''''''''''' Syntax: ITERATE ITERATE name LEAVE LEAVE name As in Rexx. These are only allowed within a LOOP construct, except that LEAVE with a name can also be used to leave labelled DO and SELECT groups. LOOP instruction '''''''''''''''' Syntax: LOOP LOOP FOREVER LOOP FOR count LOOP i=1 TO 10 BY 3 FOR n LOOP j=1 TO 100 WHILE k<7 LOOP index OVER collection LOOP ... END is the NetRexx repetition construct. LOOP follows the rules of Rexx and Object Rexx repetitive DO, except that the control variable must be a simple name (not an array reference or other term) that does not conflict with a label or control variable at an outer level. A control variable must also always be a variable or property in the current class. WHILE and UNTIL are allowed as in Rexx. 'LOOP' on its own means 'LOOP FOREVER'. 'LOOP FOR count' replaces 'DO count'. CATCH and FINALLY can be used (see "Exceptions" section for details). The FOR keyword accepts any count that can be converted to an integer (int). Negative FOR counts are treated as zero. LOOP OVER is used to work through the values in a collection of Rexx indexed variables or a Java Dictionary (such as a Hashtable). The LOOP instruction takes a snapshot of the indexes into the collection, and then for each iteration of the loop the control variable ('index', in the example above) is set to the next available index. For example: mycoll='' mycoll['Tom']=1 mycoll['Dick']=2 mycoll['Harry']=3 loop name over mycoll say mycoll[name] end might display: 3 1 2 Note that the order in which the values are returned are undefined; all that is known is that all indexes available at the start of the loop will be available and assigned to 'name' in turn as the loop iterates. The name of a loop (which may be used on END, LEAVE, and ITERATE for the loop) is the name of the control variable (if any). Alternatively, an explicit name may be specified using the LABEL keyword; this overrides any name derived from the control variable name (that is, the variable name cannot be used to refer to the loop if a label is specified). For example: loop label pooks i=1 to 10 loop label hill while j<3 ... if a=b then leave pooks ... end hill end pooks In this example, the LEAVE instruction leaves both loops. As with DO and SELECT, the PROTECT keyword may be used at the start of a LOOP instruction. If used, PROTECT is followed by a term that must resolve to an object reference; while the loop is being executed, the object is protected -- that is, the code in the loop has exclusive access to the object. For example: loop protect myobject while a<b ... end Both PROTECT and LABEL may be specified, if needed. METHOD instruction '''''''''''''''''' Syntax: METHOD arca METHOD fred(i) METHOD kitt(foo, bar) METHOD kitt(foo, bar=3) METHOD jack(i=int, j=long 3) RETURNS int METHOD jill(i=int[,,], j=int) RETURNS int[] METHOD soup(i) SIGNALS Exception, DivideByZero Introduces a method. See "Program Structure" for a description of methods. The arguments part of a METHOD instruction, in parentheses immediately following the method name, is optional and defines a list of the arguments for the method. In this list, each argument must be given a name (which must not be the same as the name of any property in the class). Each argument is also optionally assigned a type and default value, using the usual rules of assignment. If there is no assignment, the type of the argument is assumed to be 'Rexx' (netrexx.lang.Rexx). If there is no '=', or the expression to the right of the '=' returns just a type, the argument is required (that is, it must always be specified by the caller when the method is invoked). If an explicit value is given by the expression (as in the second "kitt" example above) then the argument is optional; if the caller does not provide it, then the value of the expression will be provided to the method instead. In the Java implementation of NetRexx, optional arguments may be omitted 'from the right' only. That is, arguments may not be omitted to the left of arguments that are not omitted. RETURNS describes the type of the result, which must be specified if the RETURN instructions in a method are to provide a result other than of type Rexx. SIGNALS lists the types of exceptions that the method may signal. Several other keyword options are allowed: o PUBLIC (the default) -- the method is visible outside the class. o INHERITABLE -- the method is visible outside the class, but only to subclasses of the class. o PRIVATE -- the method is only visible within the class. o STATIC -- the method is a class method (also known as a function). Static methods are invoked by giving the name of the class followed by the method, for example: Math.sin(1.3) -- calls method sin(..) in class Math (the name of the class may be omitted if it is listed in the USES phrase of the CLASS instruction). Static methods are useful for providing function that is not associated with an object. They cannot be overridden in a subclass. o PROTECT -- the method will have exclusive access to the current object (or the class, if a static method) while it runs. o ABSTRACT -- the method has no body; the method instruction is just defining a template for the method. This is the default for methods within an INTERFACE class. o FINAL -- the method cannot be overridden by a subclass. o NATIVE -- the method is implemented by the environment. NATIVE methods have no body. Constructor methods (where the method name exactly matches the class name) are allowed; their return type is assumed to be that of the class, and they simply create and modify 'this'. The first non-null clause in a constructor method may be a method call instruction where the method name is either 'this' or 'super', except if the class name is 'Object'. Note that 'this' and 'super' are valid method names only in this one context. See "Methods and constructors" for more details. NOP instruction ''''''''''''''' Syntax: NOP No operation, as in Rexx. NUMERIC instruction ''''''''''''''''''' Syntax: NUMERIC DIGITS n NUMERIC FORM keyword Affects operations on objects of type Rexx only; DIGITS sets arithmetic precision; FORM sets the format of exponential notation to 'scientific' or 'engineering'. NUMERIC may appear as a dynamically executed instruction in a method. It may also appear before the first method in a class, in which case it forms the default setting for the initialization of subsequent properties in the class and for all methods in the class. NUMERIC cannot be used if OPTIONS BINARY is in effect. OPTIONS instruction ''''''''''''''''''' Syntax: OPTIONS option-word-list Sets processor-dependent translator options. The OPTIONS instruction applies to the whole program, and must come before the first CLASS instruction (or any instruction that starts a class). The allowed option words, which are case-insensitive, are: BINARY -- assign literals binary (primitive) or String types, rather than Rexx types, and use native binary operations to implement operators. When NOBINARY is in effect, terms in expressions are converted to Rexx types before use by operators. CROSSREF -- display cross-reference listings of variables, by class. DIAG -- display diagnostic information (for development use only). FORMAT -- format the output file for better readability. Note that if this option is in effect, line numbers from the input file will not be preserved (so run-time errors and exception tracebacks may show incorrect line numbers). REPLACE -- allow replacement of the output (.java) file. The default, NOREPLACE, prevents an existing .java file being accidentally overwritten. STRICTARGS -- require that method invocations always specify parentheses, even when no arguments are supplied. STRICTASSIGN -- only allow exact type matches in assignments (this is stronger than Java requirements). This also applies to the arguments in method calls. STRICTCASE -- require that name matches be exact in case. STRICTSIGNAL -- require that uncaught checked exceptions be treated as an error. TRACE -- enables tracing (use NOTRACE to prevent tracing overheads, even if TRACE appears in program). VERBOSEn -- set the 'noisiness' of the processor (n=0 to 5; if omitted, n=3). NOVERBOSE and VERBOSE0 both suppress all informative messages. Prefixing any of the above with 'NO' turns the selected option off. For example: options binary nocrossref nostrictassign strictargs The default settings of the various options are: nobinary crossref nodiag noformat noreplace nostrictargs nostrictassign nostrictcase trace verbose3 Multiple OPTIONS instructions are allowed. When an option word is repeated (in the same instruction or not) then the last use of the word determines the state of the option. All option words may also be set as command line options when invoking the processor, by prefixing them with '-', for example: netrexxc -format -verbose4 foo.nrx In this case, the options may come before or after file specifications. Options set with the OPTIONS instruction override command-line settings. For more information, see the installation and use documentation. PACKAGE instruction ''''''''''''''''''' Syntax: PACKAGE foo.bar.fly As in Java. PACKAGE is considered to be an 'environment-dependent' instruction at present. PARSE instruction ''''''''''''''''' Syntax: PARSE term template The term is evaluated and converted (if necessary) to a Rexx string. It is then parsed according to the template and following Rexx rules, as defined in the ANSI Standard for Rexx. Any values that are used in patterns during the parse are converted to type Rexx; the results of parsing are type Rexx. Any variables used by PARSE must be a simple name (not an array reference or other term), and refer to a variable or property in the current class. Here are some examples of PARSE: foo='now is my time' parse foo a b c /* (a=='now' & b=='is' & c==' my time') */ parse foo a . . c /* (a=='now' & c=='time') */ parse foo a 'my' c /* (a=='now is ' & c==' time') */ parse foo 3 a -1 b +3 c +3 /* (a=='w is my time' & b=='ow ' & c=='is ') */ Please see Rexx documentation for full details of parse templates. By convention (automatically if the 'main' method is generated by the NetRexx processor), the 'main' method in a stand-alone NetRexx application should place the command string passed to it in the Rexx string variable called 'arg'. Hence the instruction: parse arg template will work, in a stand-alone application, in the same way as in Rexx (even though ARG is not a keyword in this case). Note that the command string may have been edited by the environment; certain characters may not be allowed, multiple blanks may have been reduced to single blanks, etc. Similarly, the special words 'ask', 'source', and 'version' allow parse ask x -- like Rexx parse pull parse source x -- uses 'Java method' followed by filename parse version x -- uses 'NetRexx' followed by version and date These three words may also be used within expressions. PROPERTIES instruction '''''''''''''''''''''' Syntax: PROPERTIES PUBLIC PROPERTIES PRIVATE VOLATILE PROPERTIES CONSTANT PROPERTIES STATIC This instruction defines the attributes of following property (instance) variables, and therefore must precede the first METHOD instruction. A PROPERTIES instruction cancels previous PROPERTIES instructions (that is, the attributes specified on PROPERTIES instructions are not cumulative). There must be at least one keyword option on PROPERTIES. Allowed options are INHERITABLE (the default, to encourage encapsulation), PRIVATE, and PUBLIC, which have the same meaning as on the METHOD instruction, and also: o CONSTANT -- the following properties define constants; their value is initialized when the class is loaded and may not be changed thereafter. o STATIC -- the following properties define variables associated with a class (rather than an object). They are initialized when the class is loaded. o VOLATILE -- the property may change asynchronously, outside the control of the class. The VOLATILE keyword should be considered experimental; at present, it is only applicable to the Java environment. RETURN instruction '''''''''''''''''' Syntax: RETURN RETURN value As in Rexx. The value is an expression; it must be possible to assign the value to the type specified after the RETURNS keyword on the METHOD instruction (if no RETURNS type was specified, the value will be converted to type Rexx). Either all the RETURN instructions in a method must return a value, or they must all not return a value. SAY instruction ''''''''''''''' Syntax: SAY expression The result of the expression is written to the standard output stream as a single line. If the final character of the result of the expression is the NUL (null) character ('\-' or '\0') then SAY will write the string without adding line termination. SELECT instruction '''''''''''''''''' Syntax: SELECT ... WHEN ... OTHERWISE ... END As in Rexx, with the addition of LABEL and PROTECT on the SELECT clause. CATCH and FINALLY can be used (see "Exceptions" section for details). If a LABEL is specified on the SELECT, then a LEAVE which specifies that label may be used to leave the SELECT construct, and the END that ends the SELECT may optionally specify the label of SELECT for added checking. For example: select label roman when a=b then say 'egal' when a<b then say 'lo' otherwise say 'hi' if a=0 then leave roman say 'a non-0' end roman In this example, if the variable A has the value 0 and B is non-zero then just 'hi' is displayed. If PROTECT is given on the SELECT it is followed by a term that must resolve to an object reference; while the SELECT construct is being executed, the object is protected -- that is, the code in the SELECT construct has exclusive access to the object. Both PROTECT and LABEL may be specified, if needed. SIGNAL instruction '''''''''''''''''' Syntax: SIGNAL IOException SIGNAL Exception("oh no!") Used to raise (throw) an exception (see "Exceptions" section for details), along with an optional description. The syntax is 'SIGNAL term'; the value of the term must be assignable to type Throwable. TRACE instruction ''''''''''''''''' Syntax: TRACE OFF TRACE METHODS TRACE ALL TRACE RESULTS Traces nothing, entry to methods in class, all clauses, or all clauses and results. TRACE should be placed before the first method in a class to affect all methods, or may be used dynamically within methods. Other instructions from Rexx '''''''''''''''''''''''''''' This lists the Rexx keyword instructions or variations that are not included in NetRexx, with NetRexx equivalents where appropriate. ADDRESS -- no equivalent concept. ARG -- obsolete; arguments are now defined on METHOD instructions. CALL -- use a method invocation clause "term(...)". Any result is discarded. CALL ON/OFF -- replaced by exception handlers (CATCH). DO repetition-count -- use LOOP FOR. DROP -- no direct equivalent; use assignment of 'null' for non-primitive classes. INTERPRET -- no equivalent. NUMERIC FUZZ -- rarely used in Rexx; however, it could be added if demand warranted. PROCEDURE -- replaced by METHOD (local variables are automatically hidden; property variables are EXPOSEd automatically) PULL -- use the keyword ASK with parse, or use Java input streams directly. PUSH and QUEUE -- not part of the language; no 'external data queue' concept. SIGNAL ON/OFF -- replaced by exception handlers (CATCH). Exceptions """""""""" NetRexx follows the block-oriented exception handling model of Java and C++. Instead of introducing a new construct, however (which can introduce extra levels of nesting in a program), it extends the DO, LOOP, and SELECT constructs to allow any block to include exception handlers. Specifically, where an END clause can appear in these constructs, zero or more CATCH instructions can be used to define exception handlers, followed by zero or one FINALLY instructions that describe 'clean-up' code for the block. The whole construct continues to be ended by an END clause. For example: if a=b then do /* could be LOOP i=1 to 10, etc. */ j=oddone(i, j) say something(7)/j catch ZeroDivide say 'oddone('i','j') returned zero' catch ex=Exception /* catches everything else, probably */ /* 'ex' is assigned the exception object */ say 'Exception:' ex.getMessage finally say 'Done!' end FINALLY, like OTHERWISE in SELECT, implies a semicolon after it, so the last SAY in the example could have appeared on the same line as the FINALLY without an intervening semicolon. The SIGNAL instruction is used to raise (throw) an exception. Program Structure """"""""""""""""" A NetRexx program permits the definition of multiple classes and methods, and also permits the writing of 'low boilerplate' programs by providing a default class and method as appropriate. The simplest documented NetRexx program might therefore be: /* This is a very simple NetRexx program */ say 'Hello World!' More generally, a NetRexx program consists of: 1. An optional prologue (PACKAGE, IMPORT, and OPTIONS instructions; only one PACKAGE instruction is permitted per program). 2. One or more class definitions, each introduced by a CLASS instruction. A class definition comprises: 1. Zero or more property variable assignments (which may just set the type of each variable), along with optional PROPERTIES instructions that can alter their attributes, and optional NUMERIC instructions. 2. Zero or more method definitions, each introduced by a METHOD instruction. Methods may contain any instructions, except the CLASS, METHOD, and PROPERTIES instructions and those allowed in the prologue. For example: /* A program with two classes */ import java.applet. -- for example class testclass extends Applet i=int -- property (instance) variable j=int 3 -- this one is initialized to 3 method start say 'I started' method stop say 'I stopped' class anotherclass method testing loop i=1 to 10 say '1, 2, 3, 4...' if i=7 then return end return method anothertest say '1, 2, 3, 4' Note that a RETURN instruction implies no static scoping; the content of a method is ended by a METHOD (or CLASS) instruction, or by the end of the source stream. The following defaults are provided: 1. If, while parsing prolog instructions, some instruction that is not valid for the prolog and is not a CLASS instruction is encountered, then a default CLASS instruction (with the name derived from that of the source file) and a default METHOD instruction (with a name and attributes appropriate for the environment, such as 'main') is inserted. In this case, it is assumed that execution of the program will begin by invocation of the default method. In other words, a 'stand-alone' application can be written without explicitly providing the class and method instructions for the first method to be executed. In the Java environment, the 'main' method in a stand-alone application is passed the words forming the command string as a String array. When NetRexx provides the method instruction by default, it also constructs a Rexx string from this array of words, with a blank added between words, and assigns the string to the variable 'arg'. The command string may also have been edited by the underlying operating system environment; certain characters may not be allowed, multiple blanks or whitespace may have been reduced to single blanks, etc. 2. If a method ends and the last instruction at the outer level of the method scope is not RETURN then an RETURN instruction is added unless a value is expected for a method, in which case an error is reported. Language processors may provide option(s) to prevent, or warn of, these defaults being applied, as desired.