--- name: "regina" section: "1" platform: "linux" package: "regina-rexx" version: "3.9.5+dfsg1-0.1+b1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/regina" --- # regina(1) 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, or is specified as \`-', the Rexx program to interpret will be read from standard input, and interpretation will start when the whole program has been read. The **regina** executable supports the use of external function packages written to the SAA API, and loaded 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. - \-l\[locale\] Allows the user to specify the *locale* to be used. Normally this switch is specified without the optional *locale string which uses the system's locale.* - \-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 Windows Explorer. - \-r Runs a Rexx program is a restricted mode where any no changes to the external environment are allowed. Writing to files, loading external function packages, and running external commands are prohibited. - \-ooptions Allows Regina OPTIONS to be passed to the Rexx program. The value of *options* is in the same format as the OPTIONS instruction. - \-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 binary 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 information 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 binary 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 \. ## Maintainer Changes to Regina since 0.07a, Mark Hessling \ with significant assistance from Florian Grosse-Coosmann. ## See Also There are several good reference books on Rexx. The most famous is "The Rexx Language" by Mike Cowlishaw. Visit https://www.rexxla.org (The Rexx Language Association) for any Rexx related information.