1regina(1) General Commands Manual regina(1)
2
6 regina - The Regina Rexx Interpreter
7
9 regina [ options ] [ script [ scriptparams ]]
10 rexx [ options ] [ script [ scriptparams ]]
12
14 regina will read the file named as script and will assume the contents
15 of that file to be a Rexx program and will interpret that program. Any
16 parameters following script will be interpreted as the parameters to
17 the Rexx program. If script is not specified, or is specified as `-',
18 the Rexx program to interpret will be read from standard input, and in‐
19 terpretation will start when the whole program has been read.
20 The regina executable supports the use of external function packages
22 written to the SAA API, and loaded with the RxFuncAdd BIF.
23 The rexx executable does not support the use of external function pack‐
25 ages written to the SAA API, but executes slightly faster than the
26 regina executable.
27
30 -tx Sets tracing of the program to the option(s); "x" specified. Any
31 TRACE commands in the program will be ignored. If you want to
32 run your program with tracing set to "Intermediate", you can use
33 the option -ti. If only -t is specified, "All" is the trace
34 mode set. Multiple tracing options can be specified. eg. To
35 specify "intermediate", "interactive" tracing, specify -ti -t?.
36 -i Starts Regina in interactive mode. No script will be executed.
39 -v Displays Regina version and exits.
42 -a Changes the way that arguments passed on the command line are
45 made available to the called Rexx program. With this switch each
46 parameter on the command line is available as a separate argu‐
47 ment, rather then the normal behaviour of only making the com‐
48 bined command line arguments available as one internal argument.
49 -l[locale]
52 Allows the user to specify the locale to be used. Normally this
53 switch is specified without the optional locale string which
54 uses the system's locale.
55 -p Relevant only on Win32 platforms. Results in a `Press ENTER key
58 to exit...' prompt to be displayed at the end of execution.
59 This is useful when a Rexx program is run from Windows Explorer.
60 -r Runs a Rexx program is a restricted mode where any no changes to
63 the external environment are allowed. Writing to files, loading
64 external function packages, and running external commands are
65 prohibited.
66 -ooptions
69 Allows Regina OPTIONS to be passed to the Rexx program. The
70 value of options is in the same format as the OPTIONS instruc‐
71 tion.
72 -c Compiles the specified script to a tokenised image and writes
75 the image to an output file which is the the only other parame‐
76 ter allowed to be supplied.
77 -e Executes the specified script as a tokenised image. All other
80 switches above are allowed. The tokenised image is not allowed
81 to be supplied via stdin.
82
86 Below is a list of all the standard built-in functions in Rexx. For a
87 more complete description of each function, see the documentation ac‐
88 companying Regina.
89 ABBREV(long,short[,length])
92 Returns `1' or 0', depending on whether short is an abbreviation
93 of long , or at least length characters.
94 ABS(number)
97 Returns the absolute value of number.
98 ADDRESS()
101 Returns the name of the current environment.
102 ARG([argno[,option]])
105 Without parameters, it returns the number of parameters. If only
106 `argno' is specified, it must be a number, and that parameter is
107 returned. `Option' can be `E', `N' or `O', and then either `0'
108 or `1' is returned, depending on whether the numbered parameter
109 existed or was omitted. The option `N' is the same as not speci‐
110 fying an option.
111 B2X(binstring)
114 Converts the binary string `binstring' to a hex string.
115 BITAND(string1[,[string2][,padchar]])
118 Returns a string which is the bitwise AND of its two first pa‐
119 rameters. The shorter string is padded with `padchar'.
120 BITOR(string1[,[string2][,padchar]])
123 Like `BITAND' but uses logical OR.
124 BITXOR(string1[,[string2][,padchar]])
127 Like `BITAND' but uses logical XOR.
128 C2D(string[,length])
131 Converts the character string `string' to a decimal number.
132 `Length' specifies the number of characters in `string' to con‐
133 vert.
134 C2X(string)
137 Converts the character string `string' to a hex string.
138 CENTER(string,length[,padchar])
141 CENTRE(string,length[,padchar])
143 Centers `string' in a string of `length' characters, using `pad‐
144 char' for padding, if necessary.
145 CHARIN([streamid][,[start][,length]])
148 Read `length' (default is 1) characters from an input stream
149 (default is the standard input stream), optionally starting at
150 position `start' (default is the current read position).
151 CHANGESTR(string1,string,string2)
154 Changes all occurrences of `string1' in the string `string' to
155 `string2'.
156 CHAROUT([streamid][,[string][,start]])
159 Writes `stream' to an output stream (default is the standard
160 output stream), starting at position `start' (default is the
161 current write position).
162 CHARS([streamid])
165 Returns the number of characters left in the input stream (de‐
166 fault is the standard input stream).
167 COMPARE(string1,string2[,padchar])
170 Returns `0' or `1', depending on whether the two strings are
171 equal. The shorter string is padded with `padchar', or space if
172 padchar is omitted.
173 CONDITION([option])
176 Performs various operations on streams, see other documentation.
177 COPIES(string,copies)
180 Returns `copies' copies of the string `string'.
181 COUNTSTR(string1,string)
184 Returns the number of occurrences of `string1' in the string
185 `string'.
186 DATATYPE(string[,option])
189 Returns the datatype of `string': `NUM' if it is a number, `LIT'
190 if it is as valid literal that does not have a variable value,
191 `VAR' if it is a variable, and `BAD' otherwise. If `option' is
192 specified, it must be one of these four, and then `0' or `1' is
193 returned, depending on whether `string' is of the named type.
194 DATE([option-out,[date,[option-in]]])
197 Returns the date, in various formats, which can be Base, Cen‐
198 tury, Days, European, Month, Normal, Ordered, Standard, USA,
199 UnixTime, or Weekday. Can also be used to convert a date `date'
200 from one format `option-in' to another; `option-out'.
201 DELSTR(string,start[,length])
204 Deletes the substring of `string' starting at position `start'
205 and having a length of `length' (default is the rest of the
206 string).
207 DELWORD(string,start[,length])
210 Deletes `length' words (default is the rest of the string) from
211 `string', starting at word number `start'
212 DIGITS()
215 Returns the current setting of NUMERIC DIGITS.
216 D2C(integer[,length])
219 Converts the decimal number `integer' to a character string of
220 length `length'.
221 D2X(integer[,length])
224 Converts the decimal number `integer' to a hex string of length
225 `length'.
226 ERRORTEXT(errno)
229 Returns the error text associated with error number `errno'.
230 `errno' can specify a sub-error number in the format n.n. eg.
231 40.1
232 FORM() Returns the current setting of NUMERIC FORM.
235 FORMAT(number[,[before][,[after][,[expp][,[expt]]]]])
238 Formats `number' into a string having `before' digits before and
239 `after' digits after the decimal point. The `expp' and `expt'
240 governs how and when to use exponential form.
241 FUZZ() Returns the current setting of NUMERIC FUZZ.
244 INSERT(string1,string2[,position[,length[,padchar]]])
247 Inserts `string1' into `string2' at position `position' and with
248 a length of `length'.
249 LASTPOS(needle,haystack[,start])
252 Seeks for `needle' in `haystack', from the end towards the
253 start.
254 LEFT(string,length[,padchar])
257 Returns the `length' leftmost characters in `string'
258 LENGTH(string)
261 Returns the number of characters in `string'.
262 LINEIN([streamid][,[line][,count]])
265 Reads a line from an input stream (default is the standard input
266 stream), optionally starting at `line'. If `count' is zero, no
267 reading is performed (only repositioning).
268 LINEOUT([streamid][,[string][,line]])
271 Writes the line `string' to an output stream (default is the
272 standard output stream, optionally starting at `line'.
273 LINES([streamid])
276 Returns the number of complete lines left in an input stream.
277 MAX(number1[,number2]...)
280 Returns the maximum of its parameters.
281 MIN(number[,number]...)
284 Returns the minimum of its parameters.
285 OVERLAY(string1,string2[,[start][,[length][,padchar]]])
288 Overwrites `string2' with contents of `string1'.
289 POS(needle,haystack[,start])
292 Seeks for first occurrence of `needle' in `haystack'.
293 QUEUED()
296 Returns the number of lines in the external data queue (stack).
297 RANDOM(max)
300 RANDOM([min][,[max][,seed]])
302 Returns a random number in the range `min' to `max' (default is
304 0 and 100000).
305 REVERSE(string)
308 Reverses the order of the characters in `string'.
309 RIGHT(string,length[,padchar])
312 Returns the `length' rightmost characters in `string'.
313 rxfuncadd(external,library,internal)
316 Loads an external function called; `internal' residing in the
317 `library' shared library. `external' is the name of the function
318 as known to the interpreter.
319 SIGN(number)
322 Returns `-1', `0', or `1', depending on the sign of `number'.
323 SOURCELINE([lineno])
326 Returns the number of lines in the source for the current
327 script, or the line specified by `lineno'.
328 SPACE(string[,[length][,padchar]])
331 Transform any sequence of spaces in `string' into exactly
332 `length' spaces, and strips off leading and trailing spaces.
333 STREAM(streamid[,option[,command]])
336 Returns information about a stream, valid options are `Command',
337 `Description', and `State'. See other documentation for more in‐
338 formation.
339 STRIP(string[,[option][,char]])
342 Strips leading and trailing `char's off `string'. `Option' can
343 be Leading, Trailing, or Both.
344 SUBSTR(string,start[,[length][,padchar]])
347 Returns the substring of `string' starting at `start' and having
348 length `length'.
349 SUBWORD(string,start[,length])
352 Returns a subsequence of `length' words from `string' starting
353 at `start'.
354 SYMBOL(name)
357 Test whether `name' is a numbol, variable, literal.
358 TIME([option-out,[time,[option-in]]])
361 Returns the time, options are Civil, Elapsed, Hours, Long, Min‐
362 utes, Normal, Reset, and Seconds. Can also be used to convert a
363 time `time' from one format `option-in' to another; `op‐
364 tion-out'.
365 TRACE([setting])
368 Returns the current trace setting, and optionally sets a new
369 one.
370 TRANSLATE(string[,[tableout][,[tablein][,padchar]]])
373 Translates characters in `string' from `tablein' to `tableout'.
374 TRUNC(number[,length])
377 Truncates `number' to `length' decimals.
378 VALUE(symbol[,[value],[pool]])
381 Returns the value of `symbol', optionally setting it to `value'
382 afterwards.
383 VERIFY(string,ref[,[option][,start]])
386 Verifies that `strings' consists of characters from `ref', and
387 returns the first character that does not match. `Option' can be
388 Match or Nomatch.
389 WORD(string,wordno)
392 Returns word number `wordno' in `string'.
393 WORDINDEX(string,wordno)
396 Returns the character position of word nun
397 WORDLENGTH(string,wordno)
400 Returns the length of word number `wordno' in `string'.
401 WORDPOS(phrase,string[,start])
404 Returns the word position of the start of `phrase' in `string'.
405 WORDS(string)
408 Returns the number of words in `string'.
409 XRANGE([start][,end])
412 Returns in alphabetic order all the characters in the character
413 set from the character `start' to the character `end'.
414 X2B(hexstring)
417 Converts the hex string `hexstring' to a binary string.
418 X2C(hexstring)
421 Converts the hex string `hexstring' to a character string.
422 X2D(hexstring[,length])
425 Converts the `length' rightmost characters of the hex string
426 `hexstring' to a decimal number.
427
432 The Regina Rexx interpreter is distributed under the GNU Library Gen‐
433 eral Public License, see the file `COPYING-LIB' in the source code dis‐
434 tribution.
435
438 Anders Christensen, University of Trondheim, Norway <an‐
439 ders@pvv.unit.no>.
440
443 Changes to Regina since 0.07a, Mark Hessling <mark (at) rexx.org> with
444 significant assistance from Florian Grosse-Coosmann.
445
448 There are several good reference books on Rexx. The most famous is "The
449 Rexx Language" by Mike Cowlishaw. Visit https://www.rexxla.org (The
450 Rexx Language Association) for any Rexx related information.
451 regina(1)