Invocation: rexx [flags] filename args where "filename" is the name of the REXX program you wish to execute, and "flags" are some optional commandline parameters, described later. Notes: 1. If the basename of "filename" does not contain a dot, then an interpreter-supplied extension (usually ".rexx") will be appended, and will become the "default extension". If the file is not found with this extension then it will be searched without the extension. If the basename of "filename" contains a dot and some following characters then these characters will become the default extension (the default extension is used when calling external functions). The interpreter-supplied extension may be changed at compile time (see the compilation instructions) or at run time by setting the environment variable REXXEXT. For example: setenv REXXEXT ".exec". 2. The argument string may be any sequence of characters, including spaces, but not including NULs (\0). Bear in mind that quotes and/or escape characters may be necessary, because the shell interprets some characters as special and removes multiple spaces. 3. The REXX program is assumed to be a text file whose lines are separated by newline characters: thus newline characters may not appear in the middle of a line. All other characters are allowed (but many characters are rejected unless they form part of a string constant or comment). 4. If the given filename does not include a path specification, then the interpreter will search through the directories listed in the REXXPATH environment variable - or, if that is not defined, the PATH environment variable - before looking in the current directory. The current directory (.) may be placed in REXXPATH to change this searching order. Thus "rexx -ta test hello there" will call the program "test.rexx" with argument "hello there" and flag "-ta". The flags which are allowed all start with a "-" and are case- insensitive. They are: -option where "option" is any option recognised by the OPTIONS instruction (see below), for example: -tracefile=test1 (note that the file name in this option is case-sensitive as usual). -v The interpreter will print out the version string (as used by "parse version"). The command "rexx -v" by itself will terminate after printing the version string, but all other forms will continue as if the -v option were not present after printing the version string. -s string The interpreter will execute the contents of "string" as -c string though it were a program. The string may contain newline characters, which will be recognised as line terminators (in contrast to the string which appears in an INTERPRET instruction). Note that if the string contains any shell metacharacters (including spaces) then it must be quoted to prevent the shell from interpreting it or splitting it up. The flags -s and -c are equivalent. The latter is provided for consistency with shell parameters. -t setting The interpreter will execute "TRACE setting" before interpreting the program. The space before the setting may be omitted, for example: -t?i. Note that the setting may need to be quoted, because "?" is a shell metacharacter. -i This equals "-t?a -s 'do forever;nop;end'". The interpreter will enter interactive mode for you to type Rexx instructions. -x This option is used for files with the execute bit set on: it prevents a ".rexx" from being appended to the filename, and it causes the first line of the file to be ignored (see below). In REXX/imc >= 1.7 this option is no longer needed (since the interpreter will find the file without the extension) unless "filename.rexx" is also in the REXXPATH or the first line of the program is invalid in Rexx. Except in the case that -i or -s is present, if a filename is omitted or "-" is specified as the filename then REXX/imc reads a program from the standard input. The option "-x" and the filename "-" terminate the commandline flags. The following parameter is assumed to be a filename (except when -i, -s or - have been specified) followed by the Rexx program parameters. To execute a program called "-", say "rexx -x -". REXX/imc allows you to write a program starting with the line: #!/path/rexx [-x] (where /path/rexx is the absolute path name of the interpreter) at the top of the file so that the program can be made executable by the system. REXX/imc will ignore the first line if it starts with "#!" or if the -x option is supplied. The line will still be there, however, so line numbers in error reports will be correct (the `sourceline' function will also recognise the existence of this line). Using the -x parameter to make REXX/imc ignore the first line allows a further trick: in order to write a rexx program which is able to be executed without knowing the exact path name to the interpreter, the first line of the program should not be as above, but as follows: exec rexx -x "$0" "$*" as long as "rexx" can be found in a directory which is on the current path. Instead of that, however, it is now more desireable to use the following line which is both a valid Rexx comment and a valid Unix command to start the interpreter. /*bin/true; exec rexx "$0" "$@" # REXX program */ The Rexx interpreter needs access to the program "rxque". It will search for this file in the following directories (in order): - that named by REXXIMC, if this environment variable is set. If it is not set, then a default which was chosen at compile time is used instead. - the path name used when invoking Rexx, if any. That is, if you type "/foo/rexx myexec", then /foo will be searched. If you type "rexx myexec", then this step will be skipped. - the directories named in the environment variable PATH - the current directory. It should not be necessary to set REXXIMC, but under certain circumstances it may speed up the initialisation time to do so. Environment Variables As described above, REXXPATH is used to search for any program which is called as a command, or PATH is used if that is not set. REXXLIB is used to search for function libraries (see the technical reference for details about function libraries). If that variable is not defined then REXX/imc looks in a path which was chosen at compile time. REXXFUNC is used to search for functions and subroutines which are not found in any library (whether they are in Rexx or another language). If that variable is not defined, then REXX/imc looks in the same place as for programs which are called as commands. As described above, REXXIMC is used to search for the "rxque" program. Each of REXXLIB, REXXFUNC, REXXPATH and PATH may be a colon-separated list of directories, but REXXIMC must be a single directory name.