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.