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.
Syntax:
CATCH ZeroDivide CATCH zd=ZeroDivide CATCH zd
(See 'Exceptions' section for details.) If no variable is specified, the exception will be caught but not saved for processing. If no type is specified, 'Exception' is assumed. 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.
Syntax:
CLASS Biped CLASS blob EXTENDS Object CLASS ape EXTENDS Biped IMPLEMENTS Sitting, Standing 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.
Several other keyword options are allowed:
Some keywords on the CLASS instruction should be considered experimental, or only applicable to the Java environment; they may end up being 'implementation defined'.
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).
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.
Syntax:
FINALLY
(See "Exceptions" section for details.) A semicolon is assumed after FINALLY.
Syntax:
IF a=b THEN i=1; ELSE i=2
As in Rexx.
Syntax:
IMPORT ibm.rexx.Rexx IMPORT ibm.rexx.
As in Java, except that trailing asterisk is omitted for the 'entire directory' form, and 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.
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.
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 key 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), and refers to 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 is not yet implemented. LOOP OVER is not yet fully defined or implemented, but will be similar to, or the same as, DO OVER in Object Rexx.
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.
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:
Rexx.date('b') -- calls method date(..) in class Rexx
Constant methods are useful for providing function that is not associated with an object. They cannot be overridden in a subclass.
Some keywords on the METHOD instruction should be considered experimental, or only applicable to the Java environment; they may end up being 'implementation defined'.
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.
Syntax:
NOP
No operation, as in Rexx.
Syntax:
NUMERIC DIGITS n
As in Rexx. Affects operations on objects of type Rexx only.
NUMERIC DIGITS 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.
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. 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 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.
Syntax:
PACKAGE foo.bar.fly
As in Java.
PACKAGE is considered to be an 'environment-dependent' instruction at present.
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. 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.
Syntax:
PROPERTIES PUBLIC PROPERTIES PRIVATE VOLATILE PROPERTIES CONSTANT
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:
The VOLATILE keyword should be considered experimental; at present, it is only applicable to the Java environment.
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.
Syntax:
SAY expression
As in Rexx. The result of the expression is written to the standard output stream as a single line.
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.
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.
Syntax:
TRACE ...
Under consideration. TRACE would automatically insert trace calls of a variety of kinds, roughly similar to Rexx. Probably not interactive at first.
The following Rexx keyword instructions or variations may (or may not) be incorporated into NetRexx in due course:
ADDRESS -- under consideration. It could become a default type for 'stand-alone' methods and/or property variables. A WITH keyword on blocks might be better.ARG -- obsolete; arguments are now defined on METHOD instructions.
CALL -- simply an alternative to the method clause "term(...)". Any result is discarded. (This will probably be omitted. If not omitted, optional parentheses around the argument list would be permitted.)
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 at present.
NUMERIC FORM -- engineering formatting should probably be provided by a constant method in the Rexx class; however, it could be added as defined in Rexx.
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).
[ previous section | contents | next section ]
From 'netrexx.doc', version 0.50.
Copyright(c) IBM Corporation, 1996. All rights reserved. ©