Ubuntu Manpage: regina - The Regina Rexx Interpreter

Name

       regina - The Regina Rexx Interpreter

Syntax

       regina [ options ] [ script [ scriptparams ]]

       rexx [ options ] [ script [ scriptparams ]]

Description

       regina  will read the file named as script and will assume the contents of that file to be a Rexx program
       and will interpret that program. Any parameters following script will be interpreted as the parameters to
       the  Rexx  program.  If script is not specified, the Rexx program to interpret will be read from standard
       input, and interpretation will start when the whole program has been read.

       If `-' is specified as script then the script will be read from standard input.

       The regina executable supports the use of external function packages written to the SAA API,  and  called
       with the rxfuncadd BIF.

       The  rexx  executable  does not support the use of external function packages written to the SAA API, but
       executes slightly faster than the regina executable.

Options

-tx Sets tracing of the program to the option(s); "x" specified. Any TRACE commands in the program
will be ignored. If you want to run your program with tracing set to "Intermediate", you can use
the option -ti. If only -t is specified, "All" is the trace mode set. Multiple tracing options
can be specified. eg. To specify "intermediate", "interactive" tracing, specify -ti -t?.

-i Starts Regina in interactive mode. No script will be executed.

-v Displays Regina version and exits.

-a Changes the way that arguments passed on the command line are made available to the called Rexx
program. With this switch each parameter on the command line is available as a separate argument,
rather then the normal behaviour of only making the combined command line arguments available as
one internal argument.

-p Relevant only on Win32 platforms. Results in a `Press ENTER key to exit...' prompt to be
displayed at the end of execution. This is useful when a Rexx program is run from Explorer.

-c Compiles the specified script to a tokenised image and writes the image to an output file which is
the the only other parameter allowed to be supplied.

-e Executes the specified script as a tokenised image. All other switches above are allowed. The
tokenised image is not allowed to be supplied via stdin.

Built-ins

       Below  is  a list of all the standard built-in functions in Rexx. For a more complete description of each
       function, see the documentation accompanying Regina.

       ABBREV(long,short[,length])
              Returns `1' or 0', depending on whether short is an abbreviation of long  ,  or  at  least  length
              characters.

       ABS(number)
              Returns the absolute value of number.

       ADDRESS()
              Returns the name of the current environment.

       ARG([argno[,option]])
              Without  parameters, it returns the number of parameters. If only `argno' is specified, it must be
              a number, and that parameter is returned. `Option' can be `E', `N' or `O', and then either `0'  or
              `1'  is  returned,  depending on whether the numbered parameter existed or was omitted. The option
              `N' is the same as not specifying an option.

       B2X(binstring)
              Converts the bin-string `binstring' to a hex-string.

       BITAND(string1[,[string2][,padchar]])
              Returns a string which is the bitwise AND of its two first  parameters.   The  shorter  string  is
              padded with `padchar'.

       BITOR(string1[,[string2][,padchar]])
              Like `BITAND' but uses logical OR.

       BITXOR(string1[,[string2][,padchar]])
              Like `BITAND' but uses logical XOR.

       C2D(string[,length])
              Converts  the  character  string  `string'  to  a decimal number. `Length' specifies the number of
              characters in `string' to convert.

       C2X(string)
              Converts the character string `string' to a hex-string.

       CENTER(string,length[,padchar])

       CENTRE(string,length[,padchar])
              Centers `string' in a string of `length' characters, using `padchar' for padding, if necessary.

       CHARIN([streamid][,[start][,length]])
              Read `length' (default is 1) characters from an  input  stream  (default  is  the  standard  input
              stream), optionally starting at position `start' (default is the current read position).

       CHANGESTR(string1,string,string2)
              Changes all occurrences of `string1' in the string `string' to `string2'.

       CHAROUT([streamid][,[string][,start]])
              Writes  `stream' to an output stream (default is the standard output stream), starting at position
              `start' (default is the current write position).

       CHARS([streamid])
              Returns the number of characters left in the input stream (default is the standard input stream).

       COMPARE(string1,string2[,padchar])
              Returns `0' or `1', depending on whether the two strings are equal.  The shorter string is  padded
              with `padchar', or space if padchar is omitted.

       CONDITION([option])
              Performs various operations on streams, see other documentation.

       COPIES(string,copies)
              Returns `copies' copies of the string `string'.

       COUNTSTR(string1,string)
              Returns the number of occurrences of `string1' in the string `string'.

       DATATYPE(string[,option])
              Returns  the  datatype  of `string': `NUM' if it is a number, `LIT' if it is as valid literal that
              does not have a variable value, `VAR' if it is a variable, and `BAD'  otherwise.  If  `option'  is
              specified,  it  must  be  one of these four, and then `0' or `1' is returned, depending on whether
              `string' is of the named type.

       DATE([option-out,[date,[option-in]]])
              Returns the date, in various formats, which can be Base, Century, Days, European,  Month,  Normal,
              Ordered,  Standard, USA, UnixTime, or Weekday.  Can also be used to convert a date `date' from one
              format `option-in' to another; `option-out'.

       DELSTR(string,start[,length])
              Deletes the substring of `string' starting at position `start' and having  a  length  of  `length'
              (default is the rest of the string).

       DELWORD(string,start[,length])
              Deletes  `length' words (default is the rest of the string) from `string', starting at word number
              `start'

       DIGITS()
              Returns the current setting of NUMERIC DIGITS.

       D2C(integer[,length])
              Converts the decimal number `integer' to a character string of length `length'.

       D2X(integer[,length])
              Converts the decimal number `integer' to a hex-string of length `length'.

       ERRORTEXT(errno)
              Returns the error text associated with error number `errno'.   `errno'  can  specify  a  sub-error
              number in the format n.n. eg. 40.1

       FORM() Returns the current setting of NUMERIC FORM.

       FORMAT(number[,[before][,[after][,[expp][,[expt]]]]])
              Formats  `number' into a string having `before' digits before and `after' digits after the decimal
              point. The `expp' and `expt' governs how and when to use exponential form.

       FUZZ() Returns the current setting of NUMERIC FUZZ.

       INSERT(string1,string2[,position[,length[,padchar]]])
              Inserts `string1' into `string2' at position `position' and with a length of `length'.

       LASTPOS(needle,haystack[,start])
              Seeks for `needle' in `haystack', from the end towards the start.

       LEFT(string,length[,padchar])
              Returns the `length' leftmost characters in `string'

       LENGTH(string)
              Returns the number of characters in `string'.

       LINEIN([streamid][,[line][,count]])
              Reads a line from an input stream (default is the standard input stream), optionally  starting  at
              `line'. If `count' is zero, no reading is performed (only repositioning).

       LINEOUT([streamid][,[string][,line]])
              Writes  the  line  `string' to an output stream (default is the standard output stream, optionally
              starting at `line'.

       LINES([streamid])
              Returns the number of complete lines left in an input stream.

       MAX(number1[,number2]...)
              Returns the maximum of its parameters.

       MIN(number[,number]...)
              Returns the minimum of its parameters.

       OVERLAY(string1,string2[,[start][,[length][,padchar]]])
              Overwrites `string2' with contents of `string1'.

       POS(needle,haystack[,start])
              Seeks for first occurrence of `needle' in `haystack'.

       QUEUED()
              Returns the number of lines in the external data queue (stack).

       RANDOM(max)

       RANDOM([min][,[max][,seed]])

              Returns a random number in the range `min' to `max' (default is 0 and 100000).

       REVERSE(string)
              Reverses the order of the characters in `string'.

       RIGHT(string,length[,padchar])
              Returns the `length' rightmost characters in `string'.

       rxfuncadd(external,library,internal)
              Loads an external function called; `internal' residing in the `library' shared library. `external'
              is the name of the function as known to the interpreter.

       SIGN(number)
              Returns `-1', `0', or `1', depending on the sign of `number'.

       SOURCELINE([lineno])
              Returns  the  number  of  lines  in  the  source  for the current script, or the line specified by
              `lineno'.

       SPACE(string[,[length][,padchar]])
              Transform any sequence of spaces in `string' into exactly `length' spaces, and strips off  leading
              and trailing spaces.

       STREAM(streamid[,option[,command]])
              Returns  infomation  about  a stream, valid options are `Command', `Description', and `State'. See
              other documentation for more information.

       STRIP(string[,[option][,char]])
              Strips leading and trailing `char's off `string'. `Option' can be Leading, Trailing, or Both.

       SUBSTR(string,start[,[length][,padchar]])
              Returns the substring of `string' starting at `start' and having length `length'.

       SUBWORD(string,start[,length])
              Returns a subsequence of `length' words from `string' starting at `start'.

       SYMBOL(name)
              Test whether `name' is a numbol, variable, literal.

       TIME([option-out,[time,[option-in]]])
              Returns the time, options are Civil, Elapsed, Hours, Long, Minutes, Normal,  Reset,  and  Seconds.
              Can also be used to convert a time `time' from one format `option-in' to another; `option-out'.

       TRACE([setting])
              Returns the current trace setting, and optionally sets a new one.

       TRANSLATE(string[,[tableout][,[tablein][,padchar]]])
              Translates characters in `string' from `tablein' to `tableout'.

       TRUNC(number[,length])
              Truncates `number' to `length' decimals.

       VALUE(symbol[,[value],[pool]])
              Returns the value of `symbol', optionally setting it to `value' afterwards.

       VERIFY(string,ref[,[option][,start]])
              Verifies  that  `strings'  consists of characters from `ref', and returns the first character that
              does not match. `Option' can be Match or Nomatch.

       WORD(string,wordno)
              Returns word number `wordno' in `string'.

       WORDINDEX(string,wordno)
              Returns the character position of word nun

       WORDLENGTH(string,wordno)
              Returns the length of word number `wordno' in `string'.

       WORDPOS(phrase,string[,start])
              Returns the word position of the start of `phrase' in `string'.

       WORDS(string)
              Returns the number of words in `string'.

       XRANGE([start][,end])
              Returns in alphabetic order all the characters in the character set from the character `start'  to
              the character `end'.

       X2B(hexstring)
              Converts the hex-string `hexstring' to a bin-string.

       X2C(hexstring)
              Converts the hex-string `hexstring' to a character string.

       X2D(hexstring[,length])
              Converts the `length' rightmost characters of the hex-string `hexstring' to a decimal number.

Copyright

       The  Regina  Rexx  interpreter  is distributed under the GNU Library General Public License, see the file
       `COPYING-LIB' in the source code distribution.

Author

       Anders Christensen, University of Trondheim, Norway <anders@pvv.unit.no>.

Maintainer

       Changes to Regina since 0.07a, Mark Hessling  <mark  (at)  rexx.org>  with  significant  assistance  from
       Florian Grosse-Coosmann.