Copyright © Martin Lafaix, 2000. All rights reserved.
Home | NetRexx | Workspace for NetRexx | Installation and User's Guide

Workspace for NetRexx Installation and User's Guide

This document is the "User's Guide" for Workspace for NetRexx.


1. Installation

(!!!Unpack, add wsnr.jar to classpass.)

2. An Overview of Workspace for NetRexx

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.

2.1. Starting Up and Winding Down

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.

2.2. The NetRexx Language

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.

2.2.1. Arithmetic Expressions

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

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

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.2.2. Some Types

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)

2.2.3. Symbols, Variables, Assignments, and Declarations

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/3
java.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

2.2.4. Conversion

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)

Some conversions can be performed automatically when NetRexx tries to evaluate your input. Other conversions must be explicitly requested.

2.2.5. Calling Functions

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)

This is a call to max with the two integer arguments 125 and 7:

say max(125, 7)

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()


say random

(!!! methods)

2.2.6. Long Lines

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 -
+ -

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

2.3. Numbers

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)

2.4. Data Structures

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]

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; end

(!!! to be continued)

2.5. Expanding to Higher Dimensions

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)

2.6. Writing Your Own Functions

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)

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)

(!!!to be continued)

2.7. A Typical Session

  (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
  (9) -> f.add(l, BorderLayout.CENTER)
  (10) -> f.doLayout
  (11) ->
  (12) -> l.setForeground(
  (13) -> f.dispose
  (14) -> )quit

2.8. System Commands

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.

3. Input Files and NetRexx Files

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.

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

3.2. The workspace.input File

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.

3.3. NetRexx Files

(!!! to be done. .nrx files are handled differently, in that they may not contain system commands.)

4. Workspace for NetRexx 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.

4.1. Introduction

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.

4.2. )cd

Command Syntax:

  )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'.

4.3. )clear

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

4.4. )display

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

4.5. )frame

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


)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'

4.6. )help

Command Syntax:

  )help commandName

Command Description:

This command displays help information about system commands. If you issue


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.

4.7. )history

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:

will start the recording of information. If the workspace is not empty, you will be asked to confirm this request. If you do so, the workspace will be cleared and history data will begin being saved. You can also turn the facility on by issuing )set history on.
will stop the recording of information. The )history )show command will not work after issuing this command. Note that this command may be issued to save time, as there is some performance penalty paid for saving the environment data. You can also turn the facility off by issuing )set history off.
)show [n]
can show previous input lines. )show will display up to twenty of the last input lines (fewer if you haven't typed in twenty lines). )show n will display up to n of the last input lines.
)write historyInputFile
creates an .input file with the input typed since the start of the session/frame or the last )clear all. If historyInputFile does not contain a period (".") in the filename, .input is appended to it. For example, )history )write chaos and )history )write chaos.input both write the input lines to a file called chaos.input in your current working directory. You can edit this file and then use )read to have Workspace for NetRexx process the contents.

Also See: ')frame', ')read', ')set'.

4.8. )import

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 from the system:

)import drop

Also See: ')set'

4.9. )numeric

Command Syntax:

  )numeric digits number
  )numeric form scientific | engineering
  )set numeric digits number
  )set numeric form scientific | engineering

Command Description:

(!!! just like the numeric instruction)

4.10. )options

Command Syntax:

  )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


To restore options to their defaults settings, issue

)options )default

The possible value for option are

default :

Also See: ')set'

4.11. )package

Command Syntax:

  )package )default
  )package packageName
  )set package default | packageName

Command Description:

(!!! just like the package instruction)

4.12. )pquit

Command Syntax:


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

4.13. )quit

Command Syntax:

  )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'.

4.14. )read

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'

4.15. )set

Command Syntax:

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

)set diag on | off
enables or disables verbose reporting of some run-time errors. (Used for debugging purpose.)
)set display depth depth
specify the maximum number of elements to display when showing an array. (Default value is 10.)
)set display depth
show the current display depth.
)set display level number
specify the maximum number of nested arrays to display when showing an array. (Default value is 4.)
)set display level
show the current display level.
)set history write protected | unprotected
specify whether or not to prompt for confirmation when attempting to overwrite an existing file with )history )write.
)set history on | off
enables or disables history.
)set import add class className
)set import add package packageName
)set import drop class className
)set import drop package packageName
adds or removes specified class or package from import list.
)set import
shows the currently imported statements.
)set interpreter on | off
set the interpreter status. If on, then valid statements will be executed. If off, then no execution will be attempted. (Mostly used for debugging purpose, or if you want to use Workspace for NetRexx on a pre-java2 platform.)
)set message prompt default
)set message prompt frame
)set message prompt label label
set the prompt status (frame displays the current frame name).
)set message prompt
shows the current prompt status.
)set numeric digits number
set the default numeric digits (i.e., for the current frame and all subsequent frames).
)set numeric digits
shows the current default numeric digits value.
)set numeric form scientific | engineering
set the default numeric form (i.e., for the current frame and all subsequent frames).
)set numeric form
shows the current default numeric form.
)set option option on | off
set the default activity of option option (i.e., for the current frame and all subsequent frames). option being one of : binary, decimal, explicit, strictargs, strictassign, strictcase, or strictsignal.
)set option option
shows the current option status.
)set package default
)set package packageName
set the current package name.
)set package
shows the current package name.
)set parser quiet | verbose
disables or enables verbose output from the parser. (Used for debugging purposes.)
)set quit protected | unprotected
set the quit status.
)set quit
shows the current quit status.
)set screen width number
set the screen width (in character).
)set screen width
shows the screen width.
)set show all | declared
set the amount of information displayed by the )show command.
)set show
shows the current show status.
)set trace
)set trace all | off | methods | results
set the default trace level (i.e., for the current frame and all subsequent frames).
)set use add className
)set use drop className
adds or removes specified class name from use list.
)set use
shows the current use list.

Also See: ')quit', ')show'

4.16. )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'

4.17. )synonym

Command Syntax:

  )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

)what synonym

To list, say, all synonyms that contain the substring "ap", issue

)what synonym ap

Also See: ')set', 'what'

4.18. )system

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'

4.19. )trace

Command Syntax:

  )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


To untrace everything that is traced, issue

)trace off

(!!! to be continued, just like the trace instruction)

4.20. )use

Command Syntax:

  )use query
  )use add className
  )use drop className

Command Description:

(!!! like the uses phrase in class instruction)

4.21. )what

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:

displays a list of system commands available. To get a description of a particular command, such as ")what", issue )help what.
lists system command synonyms.
displays all of the above types for items containing the pattern strings as substrings. The command synonym )apropos is equivalent to )what things.

Also See: ')display', ')set', and ')show'

5. The Workspace for NetRexx Application Programming Interface (API)

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:

  1. Construct a workspace by invoking either Workspace() or Workspace(frame). At this point, a workspace is created.
  2. Decide on whether you want to open an interactive session or run a script. Use the start or exec method accordingly.

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.

5.1. The Workspace Constructors

  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.

5.2. The start Method


The start method takes no arguments and starts an interactive session. The method returns when the user closes the session.

5.3. The exec Method

  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:

(Auto); uses a simple heuristic to find out the script type. If it has no extension or if its extension is ".input", then Input is assumed. If the extension is ".nrx", then NetRexx is assumed. Otherwise, if the first two characters of the script start a block comment (i.e., they are "/*"), then NetRexx is assumed. In all other cases, Input is assumed.
(Input); assumes the script follows the input file syntax.
(NetRexx); assumes the script follows the NetRexx file syntax.

5.4. The Frame Constructor

  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.

5.5. The put Method

  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.

5.6. The remove Method

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

6. Glossary

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.

1. (function) the number of arguments. 2. (operator or operation) corresponds to the arity of a function implementing the operator or operation.

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

operation or function with arity 2.

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.

a function body or loop body.

class hierarchy
hierarchy formed by class extensions. The root class is Object.

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.

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.

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

(syntax) An expression of the form method f(a); b defining function f with formal argument a and body b.

a set of bindings.

a systematic process that transforms an expression into an object called the value of the expression. Evaluation may produce side effects.

any syntactically correct program fragment.

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.

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.

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.

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

an argument of an operator (regarding an operator as a function).

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

special reserved words in the language such as "+" and "*"; operators can be either prefix or infix and have a relative precedence.

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.

(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).

(syntax) an operator such as "-" that is written before its single operand.

see pointer.

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.

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

1. the result of evaluating an expression. 2. a property associated with a variable in a binding in an environment.

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.

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.

7. Limitations

Martin Lafaix