| ADDRESS | Returns information about the current environment. |
| BEEP | Makes a sound. |
| ITERATEEXE | Launches another non-REXX program a multiple number of times, implementing filename pattern matching. Also, can print files, or execute other "actions" upon files. |
| RANDOM | Returns a number chosen at random from a range of numbers. |
| SLEEP | Momentarily halts (ie, delays) the REXX script. |
| SOURCELINE | Returns the number of lines in the script, or a particular line itself. |
Returns information about the current environment.
info = ADDRESS option
option determines what type of info is returned. It must be one of the following:
Option Meaning N (Name) The name of the current environment. I (Input) Returns a string containing the current position of the environment's input source, the type of input source, and the name of its input source. O (Output) Returns a string containing the current position of the environment's output destination, the type of output destination, and the name of its output destination. E (Error) Returns a string containing the current position of the environment's error message destination, the type of error message destination, and the name of its error message destination.
If omitted, option defaults to 'N'.
The desired info as noted above.
Makes a sound. Reginald's BEEP() also can be used to play a WAVE file.
CALL BEEP frequency, duration
frequency is the desired frequency in Hertz for the beep sound. If omitted, then frequency defaults to 1000 Hz. If using Reginald, and frequency is not a number, then it is assumed to be the name of a WAVE file to play. This name may include the full path.
If frequency is a number, then duration is the desired duration for the beep in milliseconds. If omitted, then duration defaults to 1 second. If frequency is the name of a WAVE file, then duration is the number of times to repeat the WAVE file, where 1 means to play it once only. A duration of 0 has a special meaning, and indicates that the WAVE playback should start, but BEEP() will return immediately while the WAVE is playing. The playback will automatically stop after the WAVE plays once (or it can be aborted by another call to BEEP() passing an empty string for frequency).
None.
Other interpreters may not support this function, or if BEEP() is supported, the WAVE file playback may not be supported.
CALL BEEP , 2000 |
/* Makes a 2 second beep at 1KHz */ |
BEEP('BLORT.WAV', 1) |
/* Plays the wave named BLORT.WAV once */ |
BEEP('BLORT.WAV', 0) |
/* Starts playing BLORT.WAV in the background */ |
BEEP('') |
/* Cancels BLORT.WAV in the background */ |
Calls another program a multiple number of times, passing it new args each time. The source and destination filenames can contain wildcards, and these are automatically resolved upon each call to the other program. The net result is that ITERATEEXE() can be used to specify filename args which contain wildcards to programs that themselves can't deal with wildcards. ITERATEEXE() implements a "filename global pattern matching" frontend for any program that accepts a filename argument.
It can also be used to print files, or do any other "action" that is supported by a Windows shell extension for a given filetype.
error = ITERATEEXE(program, source, destination, before, after, options)
program is the name of the desired program to run. This can contain the full path (ie, drive and directory names). You should also specify an extension if the program has one (ie, .exe or .cmd or .bat or .rexx). Alternately, program can be the name of some document or data file that is associated with a program. For example, specifying some_html_page.htm will cause the web browser associated with .htm files to open that file. If program is omitted, then ITERATEEXE defaults to sending the source files to the printer.
source is the name of the file to supply as the source filename to the program. (ie, This is the name of the file that the program operates upon). This can contain the full path. If source is omitted, "*.*" is assumed. (ie, Invoke the program upon each file in the current directory). When the source is a directory name (as opposed to a file name), the program is invoked upon all files in that directory. ITERATEEXE() never passes a program the name of any directory, so it is only used for programs that operate upon files, not directories themselves.
destination is the name of the file to supply as the destination filename to the program (if the program requires or accepts an additional filename). This can contain the full path. If destination is that name of a drive or directory, then the source arg is appended to that directory or drive name, and that becomes the destination filename passed to the program. If you want the exact same destination as source name, then pass '*.*' for the destination. If the program doesn't require a destination filename, or you don't wish to pass one, then omit destination.
The wildcards * and ? can be used when specifying the source or destination. This makes it possible to invoke the program upon more than one file with a single call to INTERATEEXE(), and also supply new names for destination files. * matches any amount of characters up to a . (dot). ? matches any one character except a . (dot).
before is any string of characters that should be placed before the source and destination filenames (ie, at the start of the line) when the args are passed to the program upon each invocation. Typically, these might be program "options" that are required before any filenames.
after is any string of characters that should be placed after the source and destination filenames (ie, at the end of the line) when the args are passed to the program upon each invocation. Typically, these might be program "options" that are required after any filenames.
options may be any of the following:
Option Meaning 'M' (Multiple) Launches multiple instances of the program -- one for each source file. 'A' (Action) program is an "action" such as Open or Play, rather than the name of a program to run. In this case, source will specify the document file(s) upon which to perform this action.
An empty string if successful, or an error message if an error.
The source filename is always specified before the destination filename when passed to the program. This means that programs which require a source and destination filename must expect the source first.
If successful, an empty string. If an error, an error message.
/* Invoke the program 'test.exe', specifying 'myfile'
* as the source arg.
*/
err = ITERATEEXE('test.exe', 'myfile')
IF err \== "" THEN SAY 'ERROR:' err
/* Invoke the program 'test.exe' upon all files in the
* C:\Windows directory.
*/
err = ITERATEEXE('test.exe', 'C:\Windows\')
IF err \== "" THEN SAY 'ERROR:' err
/* Invoke the program 'test.exe' upon all files in the C:\Windows
* directory that end in .ini extension.
*/
err = ITERATEEXE('test.exe', 'C:\Windows\*.ini')
IF err \== "" THEN SAY 'ERROR:' err
/* Invoke the program 'test.exe' upon all files in the C:\directory
* that end in .bat extension, and also supply a destination arg
* that consists of the filename with a .bak extension instead of
* the .bat
*/
err = ITERATEEXE('test.exe', 'C:\*.bat', '*.bak')
IF err \== "" THEN SAY 'ERROR:' err
/* Print all of the documents whose names end with the extension .c
* in the current directory.
*/
err = ITERATEEXE(, '*.c')
IF err \== "" THEN SAY 'ERROR:' err
/* Play all of the files in the directory C:\Media that end
* in .mpg extension, simultaneously and return immediately
* (ie, due to the 'M' option).
*/
err = ITERATEEXE('Play', 'C:\Media\*.mpg', , , , 'AM')
IF err \== "" THEN SAY 'ERROR:' err
/* Open the file MyZip.zip in the current directory, and
* wait for this action to complete before returning.
*/
err = ITERATEEXE('Open', 'MyZip.zip', , , , 'A')
IF err \== "" THEN SAY 'ERROR:' err
Returns a number chosen at random from a range of numbers.
number = RANDOM(lowerLimit, upperLimit, seed)
lowerLimit is the desired minimum value for the returned random number. If omitted, it defaults to 0. If upperLimit is omitted, but lowerLimit is specified, then lowerLimit actually functions as if it is upperLimit.
upperLimit is the desired maximum value for the returned random number. If both lowerLimit and upperLimit are omitted, then they default to 0 and 999, respectively.
seed is any number that you would like to reseed the random number generator with. If omitted, no reseeding is performed.
A random number in the desired range.
The maximum range that RANDOM() can return is 0 to 100000. (ie, The difference between lowerLimit and upperLimit cannot be greater than 100000).
Reginald's RANDOM() function is generally more random than other interpreter's RANDOM. So reseeding should not be necessary.
RANDOM(10, 20) |
/* Returns a number in the range 10 to 20, inclusive */ |
Momentarily halts (ie, delays) the REXX script for a specified amount of time.
CALL SLEEP delay
delay is the number of seconds to halt the script. If using Reginald, you may specify a fractional amount of seconds (to a millisecond precision).
None.
A call of SLEEP(0) can be used to force task-switching upon some operating systems.
Some interpreters do not have this function.
SLEEP() should be avoided in a script that also uses REXX Dialog (or some other windowing library). For REXX Dialog, you can instead use a window TIMEOUT to count off a specified period of time.
CALL SLEEP 10 |
/* Delay for 10 seconds */ |
CALL SLEEP 0.025 |
/* Delay for 25 milliseconds */ |
Returns the number of lines in the script, or a particular line itself.
result = SOURCELINE(lineNumber)
lineNumber is desired line to return. If omitted, then SOURCELINE() returns the number of lines in the script instead.
If lineNumber is specified, then SOURCELINE() returns that particular line of the script. If lineNumber is omitted, then SOURCELINE() returns the number of lines in the script.
SOURCELINE() is typically used from a condition handler to display the line that contains the error.
SOURCELINE(1) |
/* Returns the first line in the script */ |
SOURCELINE() |
/* Returns a count of lines in the script */ |