The NetRexx Tutorial - Language Basics

Language Basics

Introduction

In this chapter we overview some of the NetRexx basics for syntax and structure. To avoid making it too boring, I have tried to make it as short as possible.

Comments

Any sequence of characters delimited by a '/*' and a '*/' is considered by NetRexx as a comment and will NOT be executed. Also, any sequence of characters following a double - character will be considered as comments (up to the end of line).

Comments can be nested.

 
 /*  This is a valid comment */

 -- Another comment
 

You are totally free to write the comments as you prefer, but here are some examples:

+------------------------------------------------------------------+
| /***********************************************************/    |01
| /*                                                         */    |02
| /*   This is one type of comment                           */    |03
| /*                                                         */    |04
| /***********************************************************/    |05
|                                                                  |06
| /*                                                               |07
|  * This is another type of comment                               |08
|  */                                                              |09
|                                                                  |10
| -- Yet another set of comment                                    |11
| -- lines                                                         |12
| --                                                               |13
+------------------------------------------------------------------+
                                                               

As a matter of taste I prefer the second style; it also requires less typing effort to add a new line.

• Starting a program with a comment is indeed good programming practice and you should say what the program does and the like. The following is an example of this. It is a bit lengthy, but all this can be built automatically with a program skeleton builder (see rxtls in later chapters).

+------------------------------------------------------------------+
| /* Program   :  rxtlss                                           |01
|  * Subsystem :  rxt                                              |02
|  * Author    :  P.A.Marchesini (marchesi@shift3.cern.ch).        |03
|  * Created   :  4 Dec 1994 on marchesi@shift3.cern.ch            |04
|  * Info      :                                                   |05
|  * Copyright :  none.                                            |06
|  *                                                               |07
|  * Id     Info                                                   |08
|  * ------ ------------------------------------------------------ |09
|  * v1r000 First release.                                         |10
|  * v1r010 Latest release (see rxtlss.HISTORY file for details)   |11
|  *                                                               |12
|  */                                                              |13
+------------------------------------------------------------------+
                                                               prog2

Blank Lines

Blank lines are ignored. Enough said.

Assignments

We define as assignment the operation to store (assign) a value into a variable. The assignment operation is done with the = (equal) sign, as you can see from the following syntax diagram:

 
  variable = expression
 

Naturally, what NetRexx does is the following: the expression is evaluated, and the result is assigned to the variable. Some examples:

+------------------------------------------------------------------+ | test = 1 |01 | line = 'This is line' |02 | |03 | sum = a + b + c |04 | line = 'The sum is:' sum |05 +------------------------------------------------------------------+ ch0001.nrx

There are also other types of assignments, using the parse instruction, as we will see in later chapters.

Literal Strings

A literal string is a sequence of any characters delimited by a single quote character ' or by a double quote ". A NULL string is a string with no (zero) characters in it. Here are some examples:

+------------------------------------------------------------------+ | string = 'This is a test' |01 | string = "I'm happy to use quotes" |02 | string = 'I"m even more happy now' |03 | string = 'Enough of the "" quotes' |04 | string = '' /* a NULL string */ |05 +------------------------------------------------------------------+ quoteexample.nrx

NOTE:

• You are free to use single (') or double (") inverted commas. The only recommendation I would like to give is: Be consistent. Once you have adopted one or the other form, always use the same form Ñ at least on the same program Ñ as this is more agreeable for those reading it.
• As you have probably noticed, a double "" or " allows you to put a SINGLE " or ' in a string delimited by the given quote character.

Hexadecimal Strings

A hexadecimal string is a sequence of valid HEX characters (0-9, a-f, A-F), with a '\x' (or '\X' if you prefer).

+------------------------------------------------------------------+
| num1 = '\x00\x01'                                                |01
| crlf = '\x0D\x0A'  -- Carriage Return & Line Feed                |02
+------------------------------------------------------------------+
                                                               prog6

Special Characters

There are few of them in NetRexx, and certain of them have a special meaning when outside a literal string. These are:

 
   ;  - the delimiter
   -  - the continuation character
   :  - the label identifier
   (  - the start expression
   )  - the end expression.
   [  - array element (start).
   ]  - array element (end).
 

Delimiter Character

NetRexx does not need to be told that a statement is ended, as the End-of-Line character automatically implies this, and there is no need to type a ";" at the end of a line. But if you need to put more than one clause on a line, then you MUST use the ";" sign.

 
 statement_1 ; statement_2 ; statement_3
 

In the following example, note that the three loop loops are equivalent:

+----------------------------------------------------------------------+ | /* delim_exa.nrx |01 | */ |02 | loop i = 1 to 10 -- no delimiter |03 | say i -- |04 | end -- |05 | |06 | loop i = 1 to 10; -- delimiter |07 | say i; -- |08 | end; -- |09 | |10 | loop i = 1 to 10; say i; end; -- on only one line |11 | exit 0 |12 +----------------------------------------------------------------------+ delim_exa.nrx

Continuation Character

If your NetRexx statement is too long for one line, use the - character to signal to the interpreter that you wish to continue with the next line.

 
    statement                         -
     continuation_of_statement        -
     again_continuation_of_statement  -
     termination_of_statement
 

Here is the usual example:

+----------------------------------------------------------------------+ | /* cont_exa.nrx |01 | */ |02 | say 'Very long line' |03 | say 'Very' - |04 | 'long' - |05 | 'line.' |06 | exit 0 |07 +----------------------------------------------------------------------+ cont_exa.nrx

Variables and Constants

A variable is an object whose value may be changed during the execution of a NetRexx program. The value of a variable is a single character string that can contain any character. There are four groups of symbols:

• constant
• simple
• arrays

Constant symbols.

The symbol starts with a digit (0...9) or a period (.). Here are some valid constant symbols:

 
 
   82
   .92815
   3.1415
 
 

Simple symbols.

The simple symbol does NOT start with a digit (0...9) or a period (.), and does NOT contain a period (.). Here are some valid simple symbols:

 
 
   test
   pi_Greek
   is_it_ok?
 
 

• NOTE1: NetRexx is case insensitive: i.e. the symbols, such as TEST, test, and Test (I could go on, but I'm sure you understood what I mean), all refer to the SAME variable.
• NOTE2: An uninitialised variable is automatically trapped by NetRexx at compilation time.

Arrays.

The array is a simple symbol whose last character is a [. Here are some valid arrays:

 
 
  list[]
  a[]
  info_test[]
 
 

As a convention, if indexed by a number the stem contains the same number of items as in its stem.0 value. This is NOT done by the language itself, but as you will later see, it is useful to use this convention for arrays indexed by integers.

 
 
variable         value
--------         ----------------
list[0]          N                        ---+
list[1]          line 1 of list              |
list[2]          second line of list         |
(...)                                        |
list[N]          last line of stem list.   <-+
 
 

Resume'.

This table is a resume' of what we've seen so far concerning constants and variables. In the first column we see the definition, and in the others what it does and does not have.

 
 
             DOES                     DOES NOT                EXAMPLE
             ------------------------ ----------------------- ----------
constant     start with '.' , 0-9     -                       2 , 3.9
simple       -                        start with '.' , 0-9    pippo
array        contain [ ]              -                       list[4]
                                                              list[1,j]
 
 

Operations on Arrays.

As we have seen, arrays are a special category of variables. Consider the following small program:

+----------------------------------------------------------------------+ | -- arrayexa.nrx |01 | -- |02 | newlist = int[100] |03 | newlist[1] = 1 |04 | say newlist[1] -- will print 1 |05 | say newlist[2] -- will print 0 |06 | |07 | list = 'NULL' |08 | list[2] = 'test' |09 | say list[1] -- will print EMPTY |10 | say list[2] -- will print test |11 | |12 | exit 0 |13 +----------------------------------------------------------------------+ array_exa.nrx

NOTEs:

• line 2:

 
 *** This section is: 
  
 *** and will be available in next releases

Special Variables

 
 *** This section is: 
  
 *** and will be available in next releases

Outputting something with say

Use the instruction say to output something on your default output character stream (i.e. your screen). The format of the instruction is:

 
say expression
 

Unlike C language, in REXX you do NOT need the newline character ('\n') at the end of your expression; NetRexx automatically does it for you. Examples:

 
  list = 'you and me';
  total = 200
  say 'The list is' list'.'  ->   The list is you and me.
  say 'Total is:' total/2    ->   Total is: 100
 

Exiting a program.

Use the instruction exit to unconditionally leave a program, and (optionally) return a character string to the caller. The format is:

 
exit expression
 

Example(s):

 
  exit 34
 
  if rc <> 0 then
    do
      say 'Unrecoverable error.'
      exit 23
    end
 
 

As a convention, a program that ends correctly ( i.e. with no error ) should exit with 0; a non-zero exit code means there has been a problem.

 
exit 0     -> program ended OK
exit <> 0  -> problems
 

different error codes (or messages) might be helpful in understanding what has happened and why the program did not complete correctly.

Warning about Exit Status of UNIX Processes.

The Bourne shell puts the exit status of the previous command in the question mark (?) variable (the C shell uses the status variable instead). There is indeed a warning: this variable (status or ?) is a 255 bit (1 byte) value. So if your NetRexx program exits with (for example)

 
exit 300
or:
exit(300)
 

you will get:

 
 
echo $?      -> 44         (BOURNE shell)
echo $status -> 44         (C shell)
 
 

This 'feature' should not be underestimated. A user once contacted me to say that his program was aborting in an 'undocumented way', as the $status code he was getting was not in the man page for the program. It took me some time to realize that the return code he was getting (253) was coming from an 'exit -3' instruction.

Getting the arguments from the shell (or input line).

Another important thing you will want to do is to get the arguments from the shell whenever your program is called. In fact, what you will need to do is call a program with 'something' entered on the same line on which you typed the command, and to use this 'something' inside the program. There are several ways with NetRexx to get the arguments used to call that particular program. The simplest is to use a parse arg instruction, as in:

 
parse arg variable_name
 

What parse arg variable_name tells NetRexx is the following: "get the parameters the program was called with, and put them in the variable (a string) called variable_name". Consider this simple example:

+----------------------------------------------------------------------+ | /* parrot.nrx |01 | * echoes back what you type on command line |02 | */ |03 | parse arg s1 |04 | say 'you said "'s1'".' |05 | exit 0 |06 +----------------------------------------------------------------------+ parrot.nrx

This program was called parrot for the very simple reason that it 'parrots' back to you whatever you type in in the command line.

....................................................................
rsl3pm1 (401) java parrot toto bello
you said "toto bello".
rsl3pm1 (402) java parrot this is a long line
you said "this is a long line".
rsl3pm1 (404) java parrot `ls tu*`
you said "tu.tu".
rsl3pm1 (405) 
....................................................................
                                                         arg.example

Note that what follows the parse arg, is not necessarily a variable name: it can be any parsing template, as we will see in the chapter concerning string handling. This allows a great flexibility in parameter entering, such as in the following example:

+----------------------------------------------------------------------+ | /* parsearg.nrx |01 | * parses command line input with ONLY 2 fields |02 | */ |03 | parse arg infile outfile . |04 | say 'infile = "'infile'".' |05 | say 'outfile = "'outfile'".' |06 | exit 0 |07 +----------------------------------------------------------------------+ parsearg.nrx

What we have told NetRexx is the following: get the input argument arg; put the first word in the variable 'infile' infile; put the second word in the variable 'outfile' outfile; forget about all the rest ".". To give you the feel of it, we try it out here:

....................................................................
rsl3pm1 (412) java parsearg test out.TEST
infile  = "test".
outfile = "out.TEST".
rsl3pm1 (413) java parsearg test 
infile  = "test".
outfile = "".
rsl3pm1 (414) java parsearg test output.test some other args
infile  = "test".
outfile = "output.test".
rsl3pm1 (415) 
....................................................................
                                                        arg1.example

We will get back to parsing in a later chapter (when we'll deal with string operations).

Real Examples

Adding an item to an array (updating array[0])

If you use the convention of having stem[0] as the item count for your stem, you need to have a pointer that contains the number of items you have. Suppose that your array is called list[ ]. To save the various items in such an array, you will have to build a construct as in the following example:

 
i = 0
do loop
  (...)
  i = i+1
  list[i] = whatever_you_want
end
list[0] = i
 

Here is a better way of doing the same thing:

 
list = xarray()
do loop
  (...)
  list.ad_list whatever_you_want
end
 

We eliminate the need for the index variable i, which makes the program: a) easier to read, and b) less error prone since we 'might' for some reason overwrite the pointer variable. This approach is particularly useful for an output file: you build the various lines out output, and then, when you've finished the processing, you can write all the output (contained in the array list[ ]) in one go. The following program illustrates this approach. To repeat: in these examples are some new concepts you will find explained later on. You should not spend too much time right now on their details. What I want is to give you are real 'program-atoms' that you can put in your programs even when you have completely mastered the language. NOTEs:

• line 1: we define an object of the class xarray;
• line 2: we add an item;
• line 3: we add another one;
• line 7: we display the items we collected;

And this is what you will get running the above program:

....................................................................
rsl3pm1 (239) java xarray
Line 1
Line 2
Line 3
Line 4 (last)
rsl3pm1 (240) 
....................................................................
                                            Output of program xarray

This chapter's tricks.

Avoid the NEWLINE character.

At this point you might ask yourself: "But what if I do not want to have a NEWLINE?" In that case you cannot use say, but rather a small workaround. This is how to do it:

 

str = 'My test'
System.out.print(str'\x0D')

 

Chapter FAQ

QUESTION: Can comments be nested? Yes, comments can be nested, so you can happily write something like

 
/*
  (...)
  /* step 1.00
   * start procedure
   */
  (...)
  -- comment
  (...)
 */
 

This feature is useful if you want to comment out a whole piece of code (comments included) to easy you compilation tests.

NOTE: In JAVA comments can NOT be nested.

QUESTION: How do I do Charin/Charout screen I/O?

You use the "\-" at the end of string, like in this code atom:

 
say 'This will appear \-'
say 'as one line.'
 

which will print:

 
This will appear as one line.
 

on your terminal.

Summary

Here is a resume' of what we have seen in this chapter.

 
_ comments                        | /*   */
                                  | --
                                  | - ex.: /* this is a comment */
                                  |        -- and this another one
                                  |
_ delimiter character             | ;
                                  | - ex.: say '1' ; say '2'
                                  |
_ continuation character          | -
                                  | - ex.: say 'this is a' -
                                  |            'long line'
                                  |
_ arrays                          | variable[ ]
                                  | - ex.: list[ ]
                                  | - ex.: out[ ]
                                  |
_ reserved variable names         | 
                                  |
 

 
 *** This section is: 
  
 *** and will be available in next releases

File: nr_6.html.

Last update was done on 18 May 1998 21:47:37(GMT +2).