# Aros/Developer/Docs/Rexx

* Navbar for the Aros wikibook
* Aros User
* Aros User Docs
* Aros User FAQs
* Aros User Applications
* Aros User DOS Shell
* Aros/User/AmigaLegacy
* Aros Dev Docs
* Aros Developer Docs
* Porting Software from AmigaOS/SDL
* For Zune Beginners
* Zune .MUI Classes
* For SDL Beginners
* Aros Developer BuildSystem
* Specific platforms
* Aros x86 Complete System HCL
* Aros x86 Audio/Video Support
* Aros x86 Network Support
* Aros Intel AMD x86 Installing
* Aros Storage Support IDE SATA etc
* Aros Poseidon USB Support
* x86-64 Support
* Motorola 68k Amiga Support
* Linux and FreeBSD Support
* Windows Mingw and MacOSX Support
* Android Support
* Arm Raspberry Pi Support
* PPC Power Architecture
* misc
* Aros Public License

## Arexx

A scripting language for processing text and files.
A script is just a plain text file.
Copyrighted (William S. Hawes) extension to Rexx from IBM
ARexx is a scripting language and although you can use it to launch applications, you're better off using a regular DOS script for that, if it's required.
ARexx is far more powerful than DOS, but isn't really intended as a replacement. ARexx's principal strength is that it allows you to write scripts that can talk to "hosts"; that is, any application that has an ARexx port. This allows ARexx to control the application (within the limits of what features it exposes to ARexx). As a single script can communicate with multiple hosts, it can coordinate activity between applications. Any command it doesn't understand, it forwards to the currently selected host. By default, the host is the shell itself.
You invoke CALL searching for a function from a library (according to the documentation in this search order): 1) Internal functions 2) Built-in functions 3) Function libraries and Function Hosts 4) External AREXX programs - forward the Msg to the AREXX process itself and scan for files loaded
There are three different 'modes': - ARexx command host - function host - function library

## Tutorial
### Looping

The DO control structure always begins with a DO and ends with an END.
DO UNTIL:
DO WHILE:
Stepping through a variable:
Looping forever until exiting with LEAVE - BREAK has other possibilities, but you probably want LEAVE:
Looping a fixed number of times

### Conditionals

Testing for multiple conditions
NOP indicates no instruction is to be executed.

### Variables

There is a command that looks if a var is a integer or not... DATATYPE(WHOLE)

### Command and Function

Rexx makes difference between commands and functions. With ADDRESS you indicate a place to send a command to. Commands are always one line. Functions have to be in a library with ARexx support and be added with addlib. You seem to want function syntax but are using command port.
Changes the way that arguments passed on the command line are made available to the called Rexx program. With this switch each parameter on the command line is available as a separate argument, rather then the normal behaviour of only making the combined command line arguments available as one internal argument.
It seems indeed that 'command'-mode is not to receive more than 1 argument (arg[0]).

### PARSE

The PARSE instruction is particularly powerful; it combines some useful string-handling functions
where origin specifies the source:
* arg (command line variable)
* linein (keyboard)
* pull (REXX data queue)
* value (a literal or a function) with required to indicate where the literal ends
* var (a variable)
* version (version/release number)
and template can be:
* list of variables
* column number delimiters
* literal delimiters
upper is optional; it you specify it, data will be converted to upper case. use 'PARSE PULL var' if you don't want the input to be uppercased. 'PULL var' is the same as 'PARSE UPPER PULL var'
Examples:
Using a list of variables as template
displays the following
Using a delimiter as template:
also displays the following
Using column number delimiters:
displays the following
A template can use a combination of variables, literal delimiters, and column number delimiters.

### Advanced Data Structures

You can pass a whole stem to a function declared in THE SAME script via the "PROCEDURE EXPOSE" statement, e.g.
(take care to put the '.' or just the stem var will be visible to the function 'test', not the all stem. Any modificiation to 'stem.' will be global. There is no way to pass a stem to an external function
ARexx will also search for the function in a file with the same name as it and as <name>.rexx), both in current dir and REXX:. Don't put .rexx on my files, as ~(*:*) matches functions, *.rexx ordinary scripts, *.ced ...

### File Manipulation

Null, of course, is the absence of any data.
IBM text editors do a <CR><LF> at each <RETURN>. Most Amiga software, AFAIK, only does <LF> and the end of the file is simply indicated when there are no more bytes to be read.
The ARexx EOF indicates when you've run out of stuff to read from a file. It does not (to my knowledge) look around for whatever the IBM thinks signifies the end of a file on top of simply noticing when the file has reached its end of capacity (say you have a 1024-byte file, after reading 1024 bytes you will have reached the end of the file, or EOF).
do UNTILEF("FILE") /* Do some reading here or something */ end
Change "call readch('rfile',1)" into "say c2d(readch('rfile',1))" to display the "ascii" code. (Note that only charcodes < 127 is ASCII)

### Debugging

Syntax, loop errors, etc.
Trace
Signal

### Program IPC

Talking to DOS,
You can get the ARexx commands of any MUI program with the HELP command. Here is an example for IBrowse.
The drive specification after the HELP command is the drive and file name for the output. Of course, the program you are checking must be running so the port is available. The output will show the standard ARexx commands that every MUI program has followed by the commands specific to the particular program being checked.

### Hooks

Normally you would provide a commandlist with your application and those command would 'automatically' be processed by the hooks installed.
It's when you use commands that does not get 'processed automatically' (because they are not in the commandlist) you need to make use of the functionality you presented (like MUIA_Application_RexxHook).
Since those attributes does not seem to be in place, you would need to fallback to the ordinairy way of doing things, meaning you would somehow 'invent' how to 'sync' your normal commands with the arexx commands

## References

* ARexx guide (last updated jun-1995)
* Beginning ARexx
* Loops and Conditionals
* Aminet Guides
* Arexx references (in AmigaGuide)
Regina 3.00

### RexxSyslib
## Adding Regina/Rexx to Programs

http://aminet.net/search?query=Minrexx http://www.pcguru.plus.com/tutorial/introduction.html
It's really easy to set up your own Rexx port. It's just a standard MsgPort. If you are just going to exit on any message and not parse commands sent to the port then you don't even need to open rexxsyslib.library...
Now that the port is created we just need to wait for a message.
ProcessRexxMsg can print your message and exit but remember to ReplyMsg. If you want to parse the Arexx commands, it's not much more work. The above is pulled from a longer printed code example and uses some REXX includes from "arexx.h" and "arexxsyslib.h" but it should NOT be necessary to open rexxsyslib.library if you will exit on any message received at your port.
http://utilitybase.com/forum/index.php?action=vthread&forum=15&topic=1915
You can now send a message to this little program with the following script:
Save it as (example) 'vartest.rexx' and run it with:

## Example script

For More Examples
You can do it so it makes a value true or tries indefinitely. otherwise you can make it leave the loop using a 'Leave' command at any stage of the DO UNTIL part.
So the below loading libs works well...
find what number every key has, this can be in ARexx...
(All on one line)
CTRL-C will stop this thing. Note here that the above and RAW-KEY Intui-messages (OpenWindow/intuition, IDCMP flags) are about the only easy and *system legal* way to obtain information about keys pressed.
This will extract the filename extension (such as .lha or .8svx) along with its length. It can be useful, when renaming files. Used it in a conversion script, that can convert different file- types, so archive.lha gets archive.lzx and pic.gif gets pic.png.
This one makes a valid path, which is better to use. No more RAM:Envfilename mistake, but RAM:Env/filename Additional it makes RAM: out of Ram Disk:
Nothing special, though, you can achieve the same result (except for RAM:<-Ram Disk:) by using rexxdossupport.library/AddPart(pathname,"") - Do not forget the "".
this little sub-routine used in all my ARexx scripts, that need external ports to be available. (WaitForPort) Since not liking to write the same lines in any script, just select this routine from a GoldED list requester and it is appended to my source. The function is simple:
portname is the ARexx-port name of the application, prog is the full path to the application, in case it needs to be launched mode can be either empty or WB. If WB is used it will be started with WBRun. Sometimes this is quite useful.
The function results in a BOOL (either TRUE or FALSE) so it is easy to handle flow control.
In this routine you will find another function I use:
You can replace it by anything you want or just take it away. Use such general routines, because they are more powerful, so could have some logging in myERR or WB requesters or whatever.
Here ya go, the fastest SQRT function in Rexx I have seen yet, found in c.l.rexx
a very simple one, seldomly used, but given as some example of the Translate function to newbies and to make the function set a bit more complete. (Since there is an Upper why shouldn't be there also a Lower)
Suggest that when you open files you do something more like this to check that it was opened successfully:
Get the file size