This document is the "User's Guide" for Workspace for NetRexx.
(!!!Unpack nrws.zip, add wsnr.jar to classpass.)
Welcome to the Workspace for NetRexx environment for interactive computation and problem solving. Consider this chapter a brief, whirlwind tour of the Workspace for NetRexx world.
Before embarking on the tour, I need to brief those readers working interactively with Workspace for NetRexx on some details. Others can skip right immediately to Section 2.2.
You need to know how to start the Workspace for NetRexx system and how to stop it. I assume that Workspace for NetRexx has been correctly installed on your machine (as described in the first chapter of this document).
To begin using Workspace for NetRexx, issue the command java org.vpad.extra.workspace.Workspace to the operating system shell. There is a brief pause, some start-up messages, and then one window appears.
At the lower left of the screen there is a prompt that looks like
(1) -> _
When you want to enter input to Workspace for NetRexx, you do so on the same line after the prompt. The "1" in "(1)" is the computation step number and is incremented after you enter Workspace for NetRexx statements. Note, however, that a system command such as )clear all may change the step number in other ways. I talk step numbers more when I discuss system commands and the workspace history facility.
To exit from Workspace for NetRexx, type )quit at the input prompt and press the Enter key. You will probably be prompted with the following message:
Please enter "y" or "yes" if you really want to leave the interactive environment and return to the operating system.
You should enter yes, for example, to exit Workspace for NetRexx.
I am purposely vague in describing exactly what your screen looks like or what messages Workspace for NetRexx displays. Workspace for NetRexx runs on a number of different machines, operating systems and windowing environments, and these differences all affect the physical look of the system. You can also change the way that Workspace for NetRexx behaves via system commands described later in this chapter and in Appendix A. System commands are special commands, like )set, that begin with a closing parenthesis and are used to change your environment. For example, you can set a system variable so that you are not prompted for confirmation when you want to leave Workspace for NetRexx.
You are ready to begin your journey into the world of Workspace for NetRexx. Proceed to the first stop.
The NetRexx language is a rich language for performing interactive computations and for building components for the Java libraries. Here I present only some basic aspects of the language that you need to know for the rest of this chapter. My discussion here is intentionally informal, with details unveiled on an "as needed" basis. For more information on a particular construct, I suggest you consult The NetRexx Language definition.
For arithmetic expressions, use the "+" and "-" operators as in mathematics. Use "*" for multiplication, "/" for division, and "**" for exponentiation. When an expression contains several operators, those of highest precedence are evaluated first. For arithmetic operators, "**" has highest precedence, "*" and "/" have the next highest precedence, and "+" and "-" have the lowest precedence.
say 1 + 2 - 3 / 4 * 3 ** 2 - 1-4.75
NetRexx puts implicit parentheses around operations of higher precedence, and groups those of equal precedence from left to right. The above expression is equivalent to this.
say ((1 + 2) - ((3 / 4) * (3 ** 2))) - 1-4.75
If an expression contains subexpressions enclosed in parentheses, the parenthesized subexpressions are evaluated first (from left to right, from inside out).
say 1 + 2 - 3 / (4 * 3 ** (2 - 1))2.75
Everything in NetRexx has a type. The type determines what operations you can perform on an object and how the object can be used. An entire chapter of this document (Chapter ???) is dedicated to the interactive use of types.
(!!! to be continued)
A symbol is a literal used for the input of things like keywords, the name of variables or to identify some algorithm.
A symbol has a name beginning with an uppercase or lowercase alphabetic character, '$', '(Euro)', or '_'. Successive characters (if any) can be any of the above, or digits. Case is by default undistinguished : the symbol points is no different from the symbol Points.
A symbol can be used in Workspace for NetRexx as a variable. A variable refers to a value. To assign a value to a variable, the operator "=" is used. A variable initially has no restriction on the kinds of values to which it can refer.
This assignment gives the value 4 to a variable names x:
x = 4
To restrict the type of objects that can be assigned to a variable, use a declaration:
y = int
The declaration for y forces values assigned to y to be converted to integer values. If no such conversion is possible, NetRexx refuses to assign a value to y:
y = 2/3java.lang.NumberFormatException: Decimal part non-zero: 0.666666667
A type declaration can also be given together with an assignment. The declaration can assist NetRexx in choosing the correct operations to apply:
f = float 2/3
Any number of expressions can be given on input line. Just separate them by semicolons.
These two expressions have the same effect as the previous single expression:
f = float; f = 2/3
Objects of one type can usually be "converted" to objects of several other types. To convert an object to a new type, prefix the expression with the desired type.
say int sin(PI)0
Some conversions can be performed automatically when NetRexx tries to evaluate your input. Other conversions must be explicitly requested.
As we saw earlier, when you want to add or subtract two values, you place the arithmetic operator "+" or "-" between the two arguments denoting the values. To use most of other NetRexx operations, however, you use another syntax: write the name of the operation first, then an open parenthesis, then each arguments separated by commas, and, finally, a closing parenthesis.
This calls the operation sqrt with the single integer argument 120:
say sqrt(120)10.95445115010332
This is a call to max with the two integer arguments 125 and 7:
say max(125, 7)125
This calls an hypothetical quatern operation with four floating-point arguments:
quatern(3.4, 5.6, 2.9, 0.1)
If the operation has no arguments, you can omit the parenthesis. That is, these two expressions are equivalent:
say random()
and
say random
(!!! methods)
When you enter expressions from your keyboard, there will be time when they are too long to fit on one line. Workspace for NetRexx does not care how long your lines are, so you can let them continue from the right margin to the left side of the next line.
Alternatively, you may want to enter several shorter lines and have Workspace for NetRexx glue them together. To get this glue, put an hyphen (-) at the end of each line you wish to continue.
say 2 - + - 3
is the same as if you had entered
say 2 + 3
Comment statements begin with two consecutive hyphens and continue until the end of the line.
say 2 + 3 -- this is rather simple, no?
There is no way to write long multi-line comments other than starting each line with "--".
Workspace for NetRexx distinguishes very carefully between different kinds of numbers, how they are represented and what their properties are. Here are a sampling of some of these kinds of numbers and some things you can do with them.
(!!! to be done)
Workspace for NetRexx has a large variety of data structures available. Many data structures are particularly useful for interactive computation and others are useful for building applications. The data structures of Workspace for NetRexx are organized into class hierarchies.
A one-dimensional array is the most commonly used data structure in Workspace for NetRexx for holding objects all of the same type. One-dimensional arrays are inflexible---they are implemented using a fixed block of storage. They give equal access time to any element.
Write an array of elements using square brackets with commas separating the elements:
a = [1, -7, 11]
The index of the first element is zero. This is the value of the third element:
say a[2]11
An important point about arrays is that they are "mutable": their constituent elements can be changed "in place":
a[2] = 5; say a[0] a[1] a[2]1 -7 5
Examples of datatypes similar to one-dimensional arrays are: StringBuffer (arrays of "characters"), and BitSet (represented by array of bits).
say BitSet(32){}
A list is another data structure used to hold objects. Unlike arrays, lists can contain elements of different non-primitive types. Also, lists are usually flexible.
A simple way to create a list is to apply the operation asList to an array of elements.
(!!! to be completed, current run-time type limitation prevent the use of simple examples)
A vector is a cross between a list and a one-dimensional array. Like a one-dimensional array, a vector occupies a fixed block of storage. Its block of storage, however, has room to expand! When it gets full, it grows (a new, larger block of storage is allocated); when it has too much room, it contracts.
This creates a vector of three elements:
f = Vector(asList([2, 7, -5]))
The addAll method inserts a list at a specified point. To insert some elements between the second and third elements, use:
f.addAll(2, asList([11, -3])); say f[2, 7, 11, -3, -5]
Vectors are used to implement "stacks". A stack is an example of a data structure where elements are ordered with respect to one another.
An easy way to create a stack is to first create an empty stack and then to push elements on it:
s = Stack(); s.push("element1"); s.push("element2"); s.push("element3")
This loop extracts elements one-at-a-time from s until the stack is exhausted, displaying the elements starting from the top of the stack and going down to the bottom:
loop while \ s.empty; say s.pop; endelement3
(!!! to be continued)
To get higher dimensional aggregates, you can create one-dimensional aggregates with elements that are themselves aggregates, for example, arrays of arrays, vectors of sets, and so on.
(!!! to be continued)
Java provides you with a very large library of predefined operations and objects to compute with. You can use the Java Class Libraries to create new objects dynamically of quite arbitrary complexity. Moreover, the libraries provides a wealth of operations that allow you to create and manipulate these objects.
For many applications, you need to interact with the interpreter and write some NetRexx programs to tackle your application. Workspace for NetRexx allows you to write functions interactively, thereby effectively extending the system library. Here I give a few simple examples, leaving the details to The NetRexx Language reference manual and related publications.
I begin by looking at several ways that you can define the "factorial" function. The first way is to use an if-then-else instruction.
method fact(n) static; if n < 3 then return n; else return n*fact(n-1) say fact(50)30414093201713378043612608166064768844377641568960512000000000000
A second definition directly uses iteration.
method fac(n) static; a = 1; loop i = 2 to n; a = a * i; end; return a say fac(50)30414093201713378043612608166064768844377641568960512000000000000
(!!!to be continued)
(12) -> )clear all
(1) -> f = Frame()
(2) -> f.setTitle("Hello world!")
(3) -> f.setSize(200, 300)
(4) -> f.setPosition(20, 20)
2 +++ f.setPosition(20, 20)
+++ ^^^^^^^^^^^
+++ Error: The method 'setPosition(byte,byte)' cannot be found in
class 'java.awt.Frame' or a superclass
(5) -> f.setLocation(20, 20)
(6) -> f.setVisible(1)
(7) -> l = Label('Hi there')
(8) -> say f.getLayout
java.awt.BorderLayout[hgap=0,vgap=0]
(9) -> f.add(l, BorderLayout.CENTER)
(10) -> f.doLayout
(11) ->
(12) -> l.setForeground(Color.red)
(13) -> f.dispose
(14) -> )quit
I conclude our tour of Workspace for NetRexx with a brief discussion of system commands. System commands are special statements that start with a closing parenthesis (")"). They are used to control or display your Workspace for NetRexx environment, start operating system commands and leave Workspace for NetRexx. For example, )system is used to issue commands to the operating system from Workspace for NetRexx. Here is a brief description of some of these commands. For more information on specific commands, see Appendix 1.
Perhaps the most important user command is the )clear all command that initializes your environment. Every section and subsection in this document has an invisible )clear all that is read prior to the examples given in the section. )clear all gives you a fresh, empty environment with no user variables defined and the step number reset to 1. The )clear command can also be used to selectively clear values and properties of system variables.
Another useful system command is )read. A preferred way to develop an application in Workspace for NetRexx is to put your interactive commands into a file, say my.input file. To get Workspace for NetRexx to read this file, you use the system command )read my.input. If you need to make changes to your approach or definitions, go into your favorite editor, change my.input, then )read my.input again.
Other system commands include: )history, to display previous input lines; )display, to display properties and values of workspace variables; and )what.
This conclude your tour of Workspace for NetRexx. To disembark, issue the system command )quit to leave Workspace for NetRexx and return to the operating system.
In this chapter I discuss how to collect Workspace for NetRexx statements and commands into files and then read the contents into the workspace. I also discuss NetRexx files, which are a variation of input files.
In this section I explain what an input file is and why you would want to know about it. I discuss where Workspace for NetRexx looks for input files and how you can direct it to look elsewhere. I also show how to read the contents of an input file into the workspace and how to use the history facility to generate an input file from the statements you have entered directly into the workspace.
An input file contains NetRexx expressions and system commands. Anything that you can enter directly to Workspace for NetRexx can be put into an input file. This is how you save input functions and expressions that you wish to read into Workspace for NetRexx more than one time.
To read an input file into Workspace for NetRexx, use the )read system command. For example, you can read a file in a particular directory by issuing
)read /nrws/src/input/matrix.input
The ".input" is optional; this also works:
)read /nrws/src/input/matrix
What happens if you just enter )read matrix.input or even )read matrix? Workspace for NetRexx looks in your current working directory for input files that are not qualified by a directory name. Typically, this directory is the directory from which you invoked Workspace for NetRexx. To change the current working directory, use the )cd system command. The command )cd by itself shows the current working directory. To change it to the src/input subdirectory for user "bar", issue
)cd /user/bar/src/input
Workspace for NetRexx looks first in this directory for an input file. If it is not found, it looks in the system's directories, assuming you meant some input file that was provided with Workspace for NetRexx.
If you have the Workspace for NetRexx history facility turned on (which it is by default), you can save all the lines you have entered into the workspace by entering
)history )write
Workspace for NetRexx tells you what input file to edit to see your statements. The file is in your home directory or in the directory you specified with )cd.
When Workspace for NetRexx starts up, it tries to read the input file workspace.input from your home directory. If there is no workspace.input in your home directory, it reads the copy located in its own src/input directory. The file usually contains system commands to personalize your Workspace for NetRexx environment. In the remainder of this section I mention a few things that users frequently place in their workspace.input files.
If you do not want to be prompted for confirmation when you issue the )quit system command, place )set quit unprotected in workspace.input. If you then decide that you do want to be prompted, issue )set quit protected. This is the default setting so that new users do not leave Workspace for NetRexx inadvertently.
To see the other system variables you can set, issue )set.
(!!! to be done. .nrx files are handled differently, in that they may not contain system commands.)
This chapter describes system commands, the command-line facilities used to control the Workspace for NetRexx environment. The first section is an introduction and discusses the common syntax of the commands available.
System commands are used to perform Workspace for NetRexx environment management. Among the commands are those that display what has been defined or computed, set up multiple logical Workspace for NetRexx environments (frames), clear definitions, read files of expressions and command, show what functions are available, and terminate Workspace for NetRexx.
Each command listing begins with one or more syntax pattern descriptions plus examples of related commands. The syntax descriptions are intended to be easy to read and do not necessarily represents the most compact way of specifying all possible arguments and options; the descriptions may occasionally be redundant.
All system commands begin with a right parenthesis which should be in the first available column of the input line (that is, immediately after the input prompt, if any). System commands may be issued directly to Workspace for NetRexx or be included in .input files.
A system command argument is a word that directly follows the command name and is not followed or preceded by a right parenthesis. A system command option follows the command and is directly preceded by a right parenthesis. Options may have arguments: they directly follow the option. This example may make it easier to remember what is an option and what is an argument:
)syscmd arg1 arg2 )opt1 opt1arg1 opt2arg2 )opt2 opt2arg1 ...
In the system command descriptions, optional arguments and options are enclosed in brackets ("[" and "]"). If an argument or option name is in italics, it is meant to be a variable and must have some actual value substituted for it when the system command call is made. For example, the syntax pattern description
)read fileName [)quietly]
would imply that you must provide an actual file name for fileName but need not to use the )quietly option. Thus
)read foo.input
is a valid instance of the above pattern.
System commands names and options may be abbreviated and may be in upper or lower case. The case of actual arguments may be significant, depending on the particular situation (such as in file names). System command names and options may be abbreviated to the minimum number of starting letters so that the name or option is unique. Thus
)s Integer
is not a valid abbreviation for the )set command, because both )set and )show begin with the letter "s". Typically, two or three letters are sufficient for disambiguating names. In my descriptions of the commands, I have used no abbreviations for either command names or options.
In some syntax descriptions I use a vertical line "|" to indicate that you must specify one of the listed choices. For example, in
)set foobar on | off
only on and off are acceptable words for following foobar. I also sometimes use "..." to indicate that additional arguments or options of the listed form are allowed. Finally, in the syntax descriptions I may also list the syntax of related commands.
Command Syntax:
)cd )cd directory
Command Description:
This command sets the Workspace for NetRexx working directory. The current directory is used for looking for input files (for )read) and for writing history input files (for )history )write).
If used with no argument, this command shows the current working directory. If an argument is used, it must be a valid directory name. Except for the ")" at the beginning of the command, this has the same syntax as the operating system cd command.
Also See: ')history', and ')read'.
Command Syntax:
)clear all )clear properties all )clear properties obj1 [obj2 ...]
Command Description:
This command is used to remove functions and variable declarations, definitions and values from the workspace. To empty the entire workspace and reset the step counter to 1, issue
)clear all
To remove everything in the workspace but not reset the step counter, issue
)clear properties all
To remove everything about the object x, issue
)clear properties x
To remove everything about the objects x, y and f, issue
)clear properties x y f
The word properties may be abbreviated to the single letter "p".
)clear p all )clear p x )clear p x y f
The )display names and )display properties commands may be used to see what is currently in the workspace.
Also See: ')display', ')history'.
Command Syntax:
)display all )display properties )display properties all )display properties [obj1 [obj2 ...]] )display type all )display type [obj1 [obj2 ...]] )display names
Command Description:
This command is used to display the contents of the workspace and signatures of functions with a given name.
The command
)display names
list the names of all user-defined objects in the workspace. This is useful if you do not wish to see everything about the objects and need only be reminded of their names.
The commands
)display all )display properties )display properties all
all do the same thing: show the values and types of all variables in the workspace. If you have defined functions, their signatures and definitions will also be displayed.
To show all information about a particular variable or user functions, for example, something named d, issue
)display properties d
The word properties may be abbreviated to the single letter "p".
)display p all )display p )display p d
To just show the declared type of d, issue
)display type d )display t d
Also See: ')clear', ')history', ')set', ')show', ')what'.
Command Syntax:
)frame new frameName )frame drop [frameName] )frame next )frame last )frame names )frame import frameName [objectName1 [objectName2 ...]] )set message prompt frame
Command Description:
A frame can be thought of as a logical session within the physical session that you get when you start the system. You can have as many frames as you want, within the limits of your computer's storage, paging space, and so on. Each frame has its own step number, environment and history. You can have a variable named a in one frame and it will have nothing to do with anything that might be called a in any other frame.
To find out the names of all frames, issue
)frame names
It will indicate the name of the current frame.
You can create a new frame "quark" by issuing
)frame new quark
If you wish to go back to what you were doing in the "initial" frame, use
)frame next
or
)frame last
to cycle through the ring of available frames to get back to "initial".
If you want to throw away a frame (say "quark"), issue
)frame drop quark
If you omit the name, the current frame is dropped.
You can bring things from another frame by using )frame import. For example, to bring the f and g from the frame "quark" to the current frame, issue
)frame import quark f g
If you want everything from the frame "quark", issue
)frame import quark
You will be asked to verify that you really want everything.
There is one )set flag to make it easier to tell were you are.
)set message prompt frame
will give a prompt that looks like
initial (1) -> _
when you start up. In this case, the frame name and step make up the prompt.
Also See: ')history', ')set'
Command Syntax:
)help )help commandName
Command Description:
This command displays help information about system commands. If you issue
)help
a list of possible commands will be shown. You can also give the name or abbreviation of a system command to display information about it. For example,
)help clear
will display the description of the )clear system command.
Command Syntax:
)history )on )history )off )history )show [n] )history )write historyInputFileName )set history on | off )set history write protected | unprotected
Command Description:
The history facility within Workspace for NetRexx allows you to restore your environment to that of another session and recall previous computational results. Additional commands allow you to create an .input file of the lines typed to Workspace for NetRexx.
Workspace for NetRexx saves your input if the history facility is turned on (which is the default). This information is saved if either of
)set history on )history )on
has been issued. Issuing either
)set history off )history )off
will discontinue the recording of information.
Each frame has its own history database.
The options to the )history commands are as follows:
Also See: ')frame', ')read', ')set'.
Command Syntax:
)import query )import package packageName )import class fullClassName )import drop packageOrFullClassName
Command Description:
This command is used to query, set and remove imported packages.
When used with the query argument, this command may be used to list the names of all imported packages and classes.
The following command lists all imported packages and classes.
)import query
To remove an imported package or class, the remove argument is used. This is usually only used to correct a previous command that imported a package or a class. If, in fact, the imported package or class does exist, you are prompted for confirmation of the removal request. The following command will remove the imported package com.foo.bar from the system:
)import drop com.foo.bar
Also See: ')set'
Command Syntax:
)numeric )numeric digits number )numeric form scientific | engineering )set numeric digits number )set numeric form scientific | engineering
Command Description:
(!!! just like the numeric instruction)
Command Syntax:
)options )options )default )options option [)off] )set option option on | off
Command Description:
This command is used to specify the options in use while interpreting statements.
To list all active options, simply issue
)options
To restore options to their defaults settings, issue
)options )default
The possible value for option are
default :
Also See: ')set'
Command Syntax:
)package )package )default )package packageName )set package default | packageName
Command Description:
(!!! just like the package instruction)
Command Syntax:
)pquit
Command Description:
This command is used to terminate Workspace for NetRexx and return to the operating system. Other than by redoing all your computations, you cannot return to Workspace for NetRexx in the same state.
)pquit differs from the )quit in that it always asks for confirmation that you want to terminate Workspace for NetRexx (the "p" is for "protected"). When you enter the )quit command, Workspace for NetRexx responds
Please enter "y" or "yes" if you really want to leave the interactive environment and return to the operating system.
If you respond with y or yes, Workspace for NetRexx will terminate and return you to the operating system (or the environment from which you invoked the system). If you responded with something other that y or yes, then Workspace for NetRexx would still be running.
Also See: ')history', ')quit', ')system'.
Command Syntax:
)quit )set quit protected | unprotected
Command Description:
This command is used to terminate Workspace for NetRexx and return to the operating system. Other than by redoing all your computations, you cannot return to Workspace for NetRexx in the same state.
)quit differs from the )pquit in that it asks for confirmation only if the command
)set quit protected
has been issued. Otherwise, )quit will make Workspace for NetRexx terminate and return you to the operating system (or the environment from which you invoked the system).
The default setting is )set quit protected so that )quit and )pquit behave the same way. If you do issue
)set quit unprotected
I suggest that you do not (somehow) assign )quit to be executed when you press, say, a function key.
Also See: ')history', ')pquit', ')system'.
Command Syntax:
)read [fileName] )read [fileName] [)quiet] [)ifthere]
Command Description:
This command is used to read .input files into Workspace for NetRexx. The command
)read matrix.input
will read the contents of the file matrix.input into Workspace for NetRexx. The ".input" file extension is optional. See Section 3.1 for more information about .input files.
This command remembers the previous file you read. If you do not specify a file name, the previous file will be read.
The )ifthere option checks to see whether the .input file exists. If it does not, the )read command does nothing. If you do not use this option and the file does not exist, you are asked to give the name of an existing .input file.
The )quiet option suppresses output while the file is being read.
Also See: ')history'
Command Syntax:
)set )set label1 [... labelN] )set label1 [... labelN] newValue
Command Description:
The )set command is used to view or set system variables that control what messages are displayed, the type of output desired, the status of the history facility, and so on.
The following arguments are possible:
Also See: ')quit', ')show'
Command Syntax:
)show nameOrAbbrev )show nameOrAbbrev )operations )show nameOrAbbrev )attributes )set show all | declared
Command Description:
This commands displays information about classes. If no options are given, the )operations option is assumed. For example,
)show Rectangle )show Rectangle )operations )show java.awt.Rectangle )show java.awt.Rectangle )operations
each display basic information about the java.awt.Rectangle class constructors and then provide a listing of operations.
The basic information displayed includes the signature of the constructors and the operations.
Also See: ')display', ')set'
Command Syntax:
)synonym )synonym synonym fullCommand )what synonyms
Command Description:
This command is used to create short synonyms for system command expressions. For example, the following synonyms might simplify commands you often use.
)synonym prompt set message prompt )synonym mail system mail )synonym ls system ls
Once defined, synonyms can be used in place of the longer command expressions. Thus
)prompt frame
is the same as the longer
)set message prompt frame
To list all defined synonyms, issue either of
)synonym )what synonym
To list, say, all synonyms that contain the substring "ap", issue
)what synonym ap
Also See: ')set', 'what'
Command Syntax:
)system cmdExpression
Command Description:
This command may be used to issue commands to the operating system while remaining in Workspace for NetRexx. The cmdExpression is passed to the operating system for execution.
If you execute programs that misbehave you may not be able to return to Workspace for NetRexx. If this happens, you may have no other choice than to restart Workspace for NetRexx and restore the environment via )history )restore, if possible.
Also See: ')pquit', ')quit'
Command Syntax:
)trace )trace off )trace all )trace methods )trace results )trace var [var1 [var2 ...]]
Command Description:
This command is used to trace the execution of statements and functions defined by users.
To list all currently enabled trace functions, simply issue
)trace
To untrace everything that is traced, issue
)trace off
(!!! to be continued, just like the trace instruction)
Command Syntax:
)use query )use add className )use drop className
Command Description:
(!!! like the uses phrase in class instruction)
Command Syntax:
)what commands pattern1 [pattern2 ...] )what synonym pattern1 [pattern2 ...] )what things pattern1 [pattern2 ...] )apropos pattern1 [pattern2 ...]
Command Description:
This command is used to display lists of things in the system. The patterns are all strings and, if present, restrict the contents of the lists. Only those items that contain one or more of the strings as substrings are displayed. For example,
)what synonyms
displays all command synonyms,
)what synonyms ver
displays all command synonyms containing the substring "ver",
)what synonyms ver pr
displays all command synonyms containing the substring "ver" or the substring "pr". Output similar to the following will be displayed
------------------ System Command Synonyms ------------------
user-defined synonyms satisfying patterns:
ver pr
)apr ............................ )what things
)apropos ........................ )what things
)prompt ......................... )set message prompt
Several other things can be listed with the )what command:
Also See: ')display', ')set', and ')show'
As described above, the simplest way to use Workspace for NetRexx is to use the stand-alone interactive environment. There is also a more direct way to use Workspace for NetRexx when calling it from another NetRexx or Java program, as described here. Please note that this API is experimental and deliberately simple; suggestions for changes and improvements are welcome!
The API comprises two classes. The first class, Workspace, comprises two constructors and two methods. The second class, Frame, comprises one constructor and two methods. To use Workspace for NetRexx, the following steps are necessary:
Before step 1, you can build an environment in which the script or the interactive session will take place. To create such an environment, use the Frame(name) constructor, and the put method to fill it.
Here is a simple example, a program that creates an environment and runs a script in it:
-- Try the Workspace for NetRexx interface import org.vpad.extra.workspace options binary aString = 'Hi there!' environment = Frame('hello') -- make environment environment.put('aString', aString) -- add 'aString' object ws = Workspace(environment) -- make a workspace ws.exec('hello.nrx') -- run the script
If hello.nrx contains say aString, 'Hi there!' will then be displayed.
You can reuse a workspace for as long as you wish. The changes made by the user or the script are preserved between invocations. You can also use more than one workspace simultaneously (but in this case you must be careful and take the usual precautions if you share a common environment).
The remainder of this section describes the constructors and the methods of the Workspace for NetRexx classes in more detail.
Workspace() Workspace(environment = Frame)
The first constructor takes no arguments and builds a default workspace. The second constructor takes a Frame as an argument. This frame describes the initial environment for the workspace.
start
The start method takes no arguments and starts an interactive session. The method returns when the user closes the session.
exec(script = String[, option = String 'A'])
The exec method takes a String. This is the name of the file to be run. If it does not contain a dot, then the ".input" extension is assumed.
The methods returns after the execution of the last statement in the specified file.
Only the first character of option is significant, and it may be in either uppercase or lowercase. The following option characters are recognized:
Frame(name = String)
This constructor takes a String as an argument. It creates an empty environment. The frame name must be a valid symbol name.
put(name = Rexx, value)
The put method takes a Rexx string and a value. The value can be of any type, but must not be null. It adds the described object in the environment.
remove(name = Rexx)
The remove method takes a Rexx string. It will remove the specified object from the environment (if the environment contains an object with a corresponding name).
argument
1. (actual argument) a value passed to a function at the time of a
function call; also called an
actual parameter. 2. (formal
argument) a variable used in the definition of a function to denote
the actual argument passed when the function is called.
arity
1. (function) the number of arguments. 2. (operator or operation)
corresponds to the arity of a function implementing the operator
or operation.
assignment
(syntax) an expression of the form x = e, meaning
"assign the value of e to x". After the
evaluation, the variable
x points to an object
obtained by evaluating the expression e. If x
has a type as a result of a previous
declaration, the object assigned to
x must have a type compatible with that type. The
interpreter must often coerce the
value of e to make that happen. For example, the
expression x = float 11 first declares
x to be a float, then forces the interpreter to coerce
the Rexx string 11 to 11.0 in order to assign a
floating-point value to x.
binary
operation or function with arity 2.
binding
the association of a variable with properties such as value
and type. The top-level environment
in the interpreter consists of bindings for all user variables and
functions. When a function is applied
to arguments, a local environment of bindings is created, one for each
formal argument and local
variable.
body
a function body or loop
body.
class hierarchy
hierarchy formed by class extensions. The root class is Object.
coercion
an automatic transformation of an object of one type
to an object of a similar or desired target type. In the interpreter,
coercions and retractions are done
automatically by the interpreter when a type mismatch occurs.
Compare conversion.
conversion
the transformation of an object of one type
to one of another type. Conversions that can be performed
automatically by the interpreter are called coercions.
These happen when the interpreter encounters a type mismatch and a similar
or declared target type is needed.
declaration
(syntax) an expression of the form x = T where T
is some type. A declaration forces all values
assigned to x to be of that
type. If a value is of a different type, the interpreter will try
to coerce the value to type T.
Declarations are necessary in case of ambiguity.
definition
(syntax) An expression of the form method f(a); b
defining function f with formal argument
a and body b.
environment
a set of bindings.
evaluation
a systematic process that transforms an expression
into an object called the value of the
expression. Evaluation may produce side effects.
expression
any syntactically correct program fragment.
frame
the basic unit of an interactive session; each frame has its own
step number, environment,
and history. In one interactive session, users
can create and drop frames, and have several active frames simultaneously.
function
implementation of operation. A function
takes zero or more argument parameters
and produces a single return value.
function body
the part of a function's definition that
is evaluated when the function is called at run-time;
the part of the function definition to the right of the method
part.
history
a mechanism that records input data for an interactive session. Using
the history facility, users can save computations, review previous
steps of a computation, and restore a previous interactive session
at some later time. For details, issue the system command
)help history to the interpreter. See also
frame.
infix
(syntax) an operator placed
between two operands; also called a
binary operator. For example, in
the expression a + b, "+" is the infix
operator. Infix operators have a precedence
relative to one another.
loop body
the part of a loop following the loop clause that tells
what to do each iteration. For example, the body of the loop
loop x over S; B; end is B.
operand
an argument of an operator (regarding
an operator as a function).
operation
an abstraction of a function, described
by a signature. For example, fact(n = int) returns int
describes an operation for "the factorial of an integer".
operator
special reserved words in the language such as "+" and
"*"; operators
can be either prefix or
infix and have a relative
precedence.
pointer
a reference implemented by a link directed from one object to
another in the computer memory. An object is said to
refer to another if it has a
pointer to that other object. Objects can also refer to
themselves (cyclic references are legal). Also more than one
object can refer to the same object.
precedence
(syntax) refers to the so-called binding
power of an operator. For example, "*" has higher
binding power than "+" so that the expression a + b * c
is equivalent to a + (b * c).
prefix
(syntax) an operator such
as "-" that is written before its single
operand.
reference
see pointer.
run-time
the time when computation is done. Contrast with
compile-time, and dynamic
as opposed to static.
side effect
action that changes a component or structure of a value. See
destructive operation for details.
signature
(syntax) an expression describing the type of an
operation. A signature has the form name(source) returns
target, where source is the type of the arguments
of the operation, and target is the type of the
result.
step number
the number that precedes user input lines in an interactive session;
the output of user results is also labeled by this number.
system commands
top-level Workspace for NetRexx statements that begin with ")".
System commands allow users to query the database, read files, trace
functions, and so on.
value
1. the result of evaluating an expression.
2. a property associated with a variable
in a binding in an environment.
variable
a means of referring to an object, but not an object itself. A variable
has a name and an associated binding created
by evaluation of NetRexx expressions such
as declarations, assignments,
and definitions. In the top-level
environment of the interpreter, variables
are global variables.
workspace
an interactive record of the user input and output held in an
interactive history file. Each user input and corresponding
output expression in the workspace has a corresponding
step number. Each interactive
frame has its own workspace.