regina(1)

💖 regina — The Regina Rexx Interpreter 💖

okay bestie, sit down, grab a boba, because we're about to talk about regina, the Regina Rexx Interpreter, and honestly? she's iconic. no cap. 🫶

---

✨ SYNTAX ✨

regina [ options ] [ script [ scriptparams ]]

rexx [ options ] [ script [ scriptparams ]]

---

🌸 DESCRIPTION 🌸

so here's the vibe: regina will read the file named as script, and it's just gonna assume the contents of that file are a Rexx program, and then it interprets that program. that's the whole job. she reads, she interprets, she slays. 💅

any parameters that come after script get interpreted as the parameters to the Rexx program. like, those are the program's args, not regina's. iykyk.

if script isn't specified, or it's specified as -, then the Rexx program to interpret gets read from standard input, and interpretation starts when the whole program has been read. so like, she waits for the whole thing before she goes. patient queen. 👑

now, 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 it executes slightly faster than the regina executable. so it's giving "less features, more speed" energy. trade-offs, bestie, trade-offs. 💀

---

🎀 OPTIONS 🎀

• -tx — sets tracing of the program to the option(s); "x" specified. any TRACE commands in the program will be ignored. so 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. just vibes, no script. 🙈
• -v — displays Regina version and exits. quick lil flex and then she's gone. 💨
• -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. so like, everyone gets their own moment instead of being squished into one. main character energy for every arg. ⭐
• -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. a little "hey bestie, i'm done, press a key" moment. 🍓
• -r — runs a Rexx program in 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. she's locked in. she's in her safe space. do not test her. 🚫
• -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. note: the original literally says "the the", and we respect the lore. 👑
• -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. sorry bestie, stdin girlies, not this time. 😭

---

lowkey important reminder: that -ooptions one is doing a lot of heavy lifting, don't skip her. 💜

part 2 is coming, don't go anywhere. 🦋

✨ Built-ins ✨

Okay bestie, here's the whole list of all the standard built-in functions in Rexx. For a more complete description of each function, see the documentation accompanying Regina. Fr fr, this is the whole menu. 🫶

• 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]) — Centers string in a string of length characters, using padchar for padding, if necessary. 👑
• 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) — Returns a random number in the range min to max (default is 0 and 100000). 🍓
• 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 chars 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. Periodt. 💅

✍️ 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. 👑

🔍 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. 🌈

---

And that's the whole regina(1) manual page, bestie — source/version and date are chillin' in the footer, iykyk 💖✨