Debian Codegraph @

regina.1

raw
1 .TH regina 1
2 .SH Name
3 regina \- The Regina Rexx Interpreter
4 .SH Syntax
5 .B regina
6 [
7 .I options
8 ] [
9 .I script
10 [
11 .I scriptparams
12 ]]
13
14 .B rexx
15 [
16 .I options
17 ] [
18 .I script
19 [
20 .I scriptparams
21 ]]
22 .SH Description
23 .B regina
24 will read the file named as
25 .I script
26 and will assume the contents of that file to be a Rexx program and
27 will interpret that program. Any parameters following
28 .I script
29 will be interpreted as the parameters to the Rexx program. If
30 .I script
31 is not specified, or is specified as `\-', the Rexx program to interpret will be read
32 from standard input, and interpretation will start when the whole
33 program has been read.
34
35 The
36 .B regina
37 executable supports the use of external function packages written
38 to the SAA API, and loaded with the
39 .B RxFuncAdd
40 BIF.
41
42 The
43 .B rexx
44 executable does
45 .B not
46 support the use of external function packages written
47 to the SAA API, but executes slightly faster than the
48 .B regina
49 executable.
50
51 .SH Options
52 .
53 .IP \-tx
54 Sets tracing of the program to the option(s); "x" specified. Any
55 .B TRACE
56 commands in the program will be ignored.
57 If you want to run your program with tracing set to "Intermediate",
58 you can use the option
59 .B \-ti.
60 If only
61 .B \-t
62 is specified, "All" is the trace mode set.
63 Multiple tracing options can be specified. eg. To specify "intermediate",
64 "interactive" tracing, specify
65 .B \-ti \-t?.
66
67 .IP \-i
68 Starts Regina in interactive mode. No script will be executed.
69
70 .IP \-v
71 Displays Regina version and exits.
72
73 .IP \-a
74 Changes the way that arguments passed on the command line are made
75 available to the called Rexx program. With this switch each parameter on the
76 command line is available as a separate argument, rather then the normal
77 behaviour of only making the combined command line arguments available as one
78 internal argument.
79
80 .IP \-l[locale]
81 Allows the user to specify the
82 .I locale
83 to be used. Normally this switch is
84 specified without the optional
85 .I
86 locale string which uses the system's locale.
87
88 .IP \-p
89 Relevant only on Win32 platforms. Results in a `Press ENTER key to exit...'
90 prompt to be displayed at the end of execution. This is useful when a Rexx
91 program is run from Windows Explorer.
92
93 .IP \-r
94 Runs a Rexx program is a restricted mode where any no changes to the external
95 environment are allowed. Writing to files, loading external function packages,
96 and running external commands are prohibited.
97
98 .IP \-ooptions
99 Allows Regina OPTIONS to be passed to the Rexx program. The value of
100 .I options
101 is in the same format as the OPTIONS instruction.
102
103 .IP \-c
104 .I Compiles
105 the specified
106 .I script
107 to a tokenised image and writes the image to an output file which is the
108 the only other parameter allowed to be supplied.
109
110 .IP \-e
111 Executes the specified
112 .I script
113 as a tokenised image. All other switches above are allowed.
114 The tokenised image is not allowed to be supplied via stdin.
115
116
117 .SH Built-ins
118 Below is a list of all the standard built\-in functions in Rexx. For a
119 more complete description of each function, see the documentation
120 accompanying Regina.
121
122 .IP ABBREV(long,short[,length])
123 Returns `1' or 0', depending on whether
124 .I short
125 is an abbreviation of
126 .I long
127 , or at least
128 .I length
129 characters.
130
131 .IP ABS(number)
132 Returns the absolute value of
133 .I number.
134
135 .IP ADDRESS()
136 Returns the name of the current environment.
137
138 .IP ARG([argno[,option]])
139 Without parameters, it returns the number of parameters. If only
140 `argno' is specified, it must be a number, and that parameter is
141 returned. `Option' can be `E', `N' or `O', and then either `0' or
142 `1' is returned, depending on whether the numbered parameter existed
143 or was omitted. The option `N' is the same as not specifying an
144 option.
145
146 .IP B2X(binstring)
147 Converts the binary string `binstring' to a hex string.
148
149 .IP BITAND(string1[,[string2][,padchar]])
150 Returns a string which is the bitwise AND of its two first parameters.
151 The shorter string is padded with `padchar'.
152
153 .IP BITOR(string1[,[string2][,padchar]])
154 Like `BITAND' but uses logical OR.
155
156 .IP BITXOR(string1[,[string2][,padchar]])
157 Like `BITAND' but uses logical XOR.
158
159 .IP C2D(string[,length])
160 Converts the character string `string' to a decimal number. `Length'
161 specifies the number of characters in `string' to convert.
162
163 .IP C2X(string)
164 Converts the character string `string' to a hex string.
165
166 .IP CENTER(string,length[,padchar])
167 .IP CENTRE(string,length[,padchar])
168 Centers `string' in a string of `length' characters, using `padchar'
169 for padding, if necessary.
170
171 .IP CHARIN([streamid][,[start][,length]])
172 Read `length' (default is 1)
173 characters from an input stream (default is the standard input
174 stream), optionally starting at position `start' (default is the
175 current read position).
176
177 .IP CHANGESTR(string1,string,string2)
178 Changes all occurrences of `string1' in the string `string'
179 to `string2'.
180
181 .IP CHAROUT([streamid][,[string][,start]])
182 Writes `stream' to an output stream (default is the standard output
183 stream), starting at position `start' (default is the current write
184 position).
185
186 .IP CHARS([streamid])
187 Returns the number of characters left in the input stream (default is
188 the standard input stream).
189
190 .IP COMPARE(string1,string2[,padchar])
191 Returns `0' or `1', depending on whether the two strings are equal.
192 The shorter string is padded with `padchar', or space if padchar is
193 omitted.
194
195 .IP CONDITION([option])
196 Performs various operations on streams, see other documentation.
197
198 .IP COPIES(string,copies)
199 Returns `copies' copies of the string `string'.
200
201 .IP COUNTSTR(string1,string)
202 Returns the number of occurrences of `string1' in the string `string'.
203
204 .IP DATATYPE(string[,option])
205 Returns the datatype of `string': `NUM' if it is a number, `LIT' if it
206 is as valid literal that does not have a variable value, `VAR' if it
207 is a variable, and `BAD' otherwise. If `option' is specified, it must
208 be one of these four, and then `0' or `1' is returned, depending on
209 whether `string' is of the named type.
210
211 .IP DATE([option\-out,[date,[option\-in]]])
212 Returns the date, in various formats, which can be Base, Century,
213 Days, European, Month, Normal, Ordered, Standard, USA, UnixTime, or Weekday.
214 Can also be used to convert a date `date' from one format `option-in'
215 to another; `option-out'.
216
217 .IP DELSTR(string,start[,length])
218 Deletes the substring of `string' starting at position `start' and
219 having a length of `length' (default is the rest of the string).
220
221 .IP DELWORD(string,start[,length])
222 Deletes `length' words (default is the rest of the string) from
223 `string', starting at word number `start'
224
225 .IP DIGITS()
226 Returns the current setting of NUMERIC DIGITS.
227
228 .IP D2C(integer[,length])
229 Converts the decimal number `integer' to a character string of length
230 `length'.
231
232 .IP D2X(integer[,length])
233 Converts the decimal number `integer' to a hex string of length
234 `length'.
235
236 .IP ERRORTEXT(errno)
237 Returns the error text associated with error number `errno'.
238 `errno' can specify a sub\-error number in the format n.n. eg. 40.1
239
240 .IP FORM()
241 Returns the current setting of NUMERIC FORM.
242
243 .IP FORMAT(number[,[before][,[after][,[expp][,[expt]]]]])
244 Formats `number' into a string having `before' digits before and
245 `after' digits after the decimal point. The `expp' and `expt' governs
246 how and when to use exponential form.
247
248 .IP FUZZ()
249 Returns the current setting of NUMERIC FUZZ.
250
251 .IP INSERT(string1,string2[,position[,length[,padchar]]])
252 Inserts `string1' into `string2' at position `position' and with a
253 length of `length'.
254
255 .IP LASTPOS(needle,haystack[,start])
256 Seeks for `needle' in `haystack', from the end towards the start.
257
258 .IP LEFT(string,length[,padchar])
259 Returns the `length' leftmost characters in `string'
260
261 .IP LENGTH(string)
262 Returns the number of characters in `string'.
263
264 .IP 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 reading
267 is performed (only repositioning).
268
269 .IP LINEOUT([streamid][,[string][,line]])
270 Writes the line `string' to an output stream (default is the standard
271 output stream, optionally starting at `line'.
272
273 .IP LINES([streamid])
274 Returns the number of complete lines left in an input stream.
275
276 .IP MAX(number1[,number2]...)
277 Returns the maximum of its parameters.
278
279 .IP MIN(number[,number]...)
280 Returns the minimum of its parameters.
281
282 .IP OVERLAY(string1,string2[,[start][,[length][,padchar]]])
283 Overwrites `string2' with contents of `string1'.
284
285 .IP POS(needle,haystack[,start])
286 Seeks for first occurrence of `needle' in `haystack'.
287
288 .IP QUEUED()
289 Returns the number of lines in the external data queue (stack).
290
291 .IP RANDOM(max)
292 .IP RANDOM([min][,[max][,seed]])
293
294 Returns a random number in the range `min' to `max' (default is 0 and
295 100000).
296
297 .IP REVERSE(string)
298 Reverses the order of the characters in `string'.
299
300 .IP RIGHT(string,length[,padchar])
301 Returns the `length' rightmost characters in `string'.
302
303 .IP rxfuncadd(external,library,internal)
304 Loads an external function called; `internal' residing in the
305 `library' shared library. `external' is the name of the function
306 as known to the interpreter.
307
308 .IP SIGN(number)
309 Returns `\-1', `0', or `1', depending on the sign of `number'.
310
311 .IP SOURCELINE([lineno])
312 Returns the number of lines in the source for the current script, or
313 the line specified by `lineno'.
314
315 .IP SPACE(string[,[length][,padchar]])
316 Transform any sequence of spaces in `string' into exactly `length'
317 spaces, and strips off leading and trailing spaces.
318
319 .IP STREAM(streamid[,option[,command]])
320 Returns information about a stream, valid options are `Command',
321 `Description', and `State'. See other documentation for more
322 information.
323
324 .IP STRIP(string[,[option][,char]])
325 Strips leading and trailing `char's off `string'. `Option' can be
326 Leading, Trailing, or Both.
327
328 .IP SUBSTR(string,start[,[length][,padchar]])
329 Returns the substring of `string' starting at `start' and having
330 length `length'.
331
332 .IP SUBWORD(string,start[,length])
333 Returns a subsequence of `length' words from `string' starting at `start'.
334
335 .IP SYMBOL(name)
336 Test whether `name' is a numbol, variable, literal.
337
338 .IP TIME([option\-out,[time,[option\-in]]])
339 Returns the time, options are Civil, Elapsed, Hours, Long, Minutes,
340 Normal, Reset, and Seconds.
341 Can also be used to convert a time `time' from one format `option\-in'
342 to another; `option\-out'.
343
344 .IP TRACE([setting])
345 Returns the current trace setting, and optionally sets a new one.
346
347 .IP TRANSLATE(string[,[tableout][,[tablein][,padchar]]])
348 Translates characters in `string' from `tablein' to `tableout'.
349
350 .IP TRUNC(number[,length])
351 Truncates `number' to `length' decimals.
352
353 .IP VALUE(symbol[,[value],[pool]])
354 Returns the value of `symbol', optionally setting it to `value'
355 afterwards.
356
357 .IP VERIFY(string,ref[,[option][,start]])
358 Verifies that `strings' consists of characters from `ref', and returns
359 the first character that does not match. `Option' can be Match or
360 Nomatch.
361
362 .IP WORD(string,wordno)
363 Returns word number `wordno' in `string'.
364
365 .IP WORDINDEX(string,wordno)
366 Returns the character position of word nun
367
368 .IP WORDLENGTH(string,wordno)
369 Returns the length of word number `wordno' in `string'.
370
371 .IP WORDPOS(phrase,string[,start])
372 Returns the word position of the start of `phrase' in `string'.
373
374 .IP WORDS(string)
375 Returns the number of words in `string'.
376
377 .IP XRANGE([start][,end])
378 Returns in alphabetic order all the characters in the character set
379 from the character `start' to the character `end'.
380
381 .IP X2B(hexstring)
382 Converts the hex string `hexstring' to a binary string.
383
384 .IP X2C(hexstring)
385 Converts the hex string `hexstring' to a character string.
386
387 .IP X2D(hexstring[,length])
388 Converts the `length' rightmost characters
389 of the hex string `hexstring' to a decimal number.
390
391
392
393 .SH Copyright
394 The Regina Rexx interpreter is distributed under the GNU Library
395 General Public License, see the file `COPYING\-LIB' in the source code
396 distribution.
397
398 .SH Author
399 Anders Christensen, University of Trondheim, Norway
400 <[email protected]>.
401
402 .SH Maintainer
403 Changes to Regina since 0.07a, Mark Hessling
404 <mark (at) rexx.org>
405 with significant assistance from Florian Grosse\-Coosmann.
406
407 .SH See Also
408 There are several good reference books on Rexx. The most famous is
409 "The Rexx Language" by Mike Cowlishaw.
410 Visit https://www.rexxla.org (The Rexx Language Association) for any Rexx
411 related information.
412