regina/regina.1

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