AmigaOS Documentation Wiki - User contributions [en]

AmigaGuide 101

2025-02-12T10:04:54Z

James Jacobs: Fixed SYSTEM action command example

''adapted from the original AmigaMail article by Jerry Hartzler''

== Introduction ==

Compared to other platforms, Amiga-based utilities that display on-line documentation are relatively weak. Until 1991, Amiga users had to rely on basic text viewing utilities like More, which lack the navigational capabilities of hypertext programs. In a hypertext environment, when the user wants more information on a subject, the user simply clicks on a word and the hypertext utility automatically cross references the subject. No type of hypertext-like utility was available on the Amiga--that is, until AmigaGuide came along.

[[AmigaGuide]] can display plain ASCII text files and AmigaGuide databases. An AmigaGuide database is a single file that consists of a set of documents called nodes. If you were to convert a book into an AmigaGuide database, a convenient way to organize the database is to make each chapter of the book into a node. Each node may contain references to other nodes (chapters) or databases (other books), using a link. When a user selects a link--which usually appears in the form of a button within the text--AmigaGuide dereferences the link and displays its node. This makes it easier for the user to find the information he is looking for because the user no longer needs to search through a document. AmigaGuide already knows where the information is.

Buttons within AmigaGuide can do other actions as well, such as execute Shell or ARexx commands. An ARexx port is also built into AmigaGuide providing users the means to support and control the utility. Therefore, like a book, an AmigaGuide database can display illustrations. It can go a step beyond by playing sounds and music, and by being truly interactive with the user, able to ask questions and evaluate responses.

This article was written to familiarize you with AmigaGuide and the format of its databases.

== Setting up AmigaGuide ==

AmigaGuide consists of the AmigaGuide utility and an Exec library called amigaguide.library. AmigaGuide should be placed in the SYS:Utilities drawer and amigaguide.library placed in the Libs: drawer. As of Release 3, the OS comes with a utility called MultiView that understands and displays AmigaGuide databases. MultiView requires amigaguide.datatype and datatypes.library in order to display AmigaGuide databases.

AmigaGuide can run from the Workbench or the Shell. To run from Workbench, the default tool of an AmigaGuide database or text icon should be set to '''AmigaGuide'''.

From the Shell, use the following command template:

AmigaGuide <my_DataBase>

where <my_DataBase> is the name of the AmigaGuide database or text file to display.

For example:

1> AmigaGuide Autodocs

attempts to open the Autodocs database. In its search for a database, AmigaGuide will first look in the current directory and then through the AmigaGuide path for the database.

The AmigaGuide path is a global environment variable. AmigaGuide stores its environment variables in the ENV:AmigaGuide directory assigned in RAM:.

The variable named path contains the list of directory names that AmigaGuide will search through when it attempts to open a database. Directory names are separated by a space. The path variable is set and stored in the ENV:AmigaGuide directory through the use of the AmigaDOS SetEnv command (Note that as of Release 3, if the AmigaGuide directory does not exist, SetEnv will not create it).

For example:

1> SetEnv AmigaGuide/Path "Workbench:Autodocs Workbench:Includes"

Of course all variables set in RAM: disappear once the computer is turned off. To prevent this, copy the file ENV:AmigaGuide/Path to the ENVARC:AmigaGuide directory. The system copies the ENVARC: directory to ENV: upon start-up.

The MultiView utility uses the amigaguide.datatype which uses this the environment variable as its path.

== The AmigaGuide Window ==

AmigaGuide displays text within an Intuition window. The window contains scroll bars, buttons and pull-down menus making it easy to browse, search and print text.

[[File:Amigaguide.png]]

Along the top edge of the AmigaGuide window is a row of six navigation buttons:

* Contents: This button displays the Table Of Contents for the current database or node. See the @NODE and @TOC commands below.

* Index: This button displays the Index for the current database. See the @INDEX command below.

* Help: By default, this button displays the database named help.guide in the s: directory. Under 3.0, the database is named amigaguide.guide in the Help:<country>/sys directory. This database contains help in using AmigaGuide.

* Retrace: This button goes back to the previous node.

* Browse: These buttons step through the nodes in sequential order (the order they appear in the database).

== AmigaGuide Databases ==

Creating an AmigaGuide database is quite simple. An AmigaGuide database is basically an ASCII text file, embedded with commands to tell AmigaGuide what to do. Let's take a look at the commands used in AmigaGuide and then make up a simple database.

There are three types of AmigaGuide commands. Database commands break up a document into nodes. Node commands set attributes within a node. Action commands are only found within a special node command called a '''link point'''. As the name implies, action commands perform some action.

=== Database Commands ===

Database commands should not be used within the nodes themselves. They must start in the first column of a line. If a line in an AmigaGuide database begins with an at (@) sign, then AmigaGuide interprets the line as a command. Although the AmigaGuide commands appear here in upper-case, AmigaGuide commands are not case sensitive.

* @DATABASE <name> - This command identifies a file as an AmigaGuide database. It must be the first line of the database.

* @NODE <name> <title> - This command indicates the start of a node. The first node of a database should be named MAIN. MAIN is typically the master table of contents for the database (see the @TOC node command in the next section). When AmigaGuide displays the node, it displays <title> in the window's title bar. If there are any spaces in the <title>, it must be in quotes. A node name cannot contain spaces, tabs, colons (':') or slants ('/').

* @DNODE <name> - This command indicates the start of a dynamic node. Dynamic nodes are beyond the scope of this introductory article and therefore are not discussed here.

* @INDEX <node name> - This command tells AmigaGuide which node to use as the index for the database. When the user hits the '''Index''' button at the top of the AmigaGuide window, AmigaGuide will display the node specified by this command. The node can be in another database. If the node is in another database, the node name is the file name of the database followed by a slant (`/`), followed by the name of the node in the other database. For example, to access the MAIN node in another database called other_database, the link point looks like this:

@{"my label" LINK other_database/MAIN}

''The name of the other database can contain a full path to the other database. If it doesn't, AmigaGuide will search the AmigaGuide path for the other database.''

* @REMARK <remark> - This commands lets you add programmer remarks to a database. AmigaGuide ignores the remarks.

=== Node Commands ===

These commands are only valid within a @NODE. They must start in the
first column of a line unless otherwise noted.

* @ENDNODE <name> - This command ends a node.

* @TITLE <title> - AmigaGuide displays <title> in the node's window title bar. It must start at the beginning of a line. This command isn't necessary if you use the <title> option in @NODE.

* @TOC <node name> - This command tells AmigaGuide which node to display when the user hits the Contents button while displaying this node. If a node does not have a @TOC command, the table of contents defaults to MAIN. The <node name> can be in another database. See the @INDEX command in the [[#Database Commands|Database Commands]] section for more information on the format of <node name>.

* @PREV <node name> - The Browse buttons can be reprogrammed so as not to step through the nodes in sequential order. For example, if this command appears in a @NODE, AmigaGuide will display the <node name> node when the user selects the '''< Browse''' button while in the current node. The <node name> can be in another database. See the @INDEX command in the [[#Database Commands|Database Commands]] section for more information on the format of <node name>.

* @NEXT <node name> - Similar to @PREV but will display the <node name> node when the user selects '''Browse >''' button while in the current node. The <node name> can be in another database. See the @INDEX command in the [[#Database Commands|Database Commands]] section for more information on the format of <node name>.

* @{"<label>" <action command>} - This command is referred to as a link point. AmigaGuide makes the string <label> into a button. The <label> must be enclosed by quotes. When the user hits that button, AmigaGuide carries out <action command> (see the next section of this article for a description of action commands). A link point does not have to start in the first column, it can appear anywhere on a line.

=== Action Commands ===

These commands are for use with the link point command described in the [[#Node Commands|Node Commands]] section of this article.

* LINK <node name> <line#> - This command loads and displays the <node name> node at the line number specified in <line #>. The <line #> parameter is optional and it defaults to zero. The node can be in another database. The <node name> can be in another database. See the @INDEX command in the [[#Database Commands|Database Commands]] section for more information on the format of <node name>.

''The <line #> parameter is optional and it defaults to zero. The default line number is line zero.''

* RX <ARexx command> - This commands executes the ARexx macro named in <ARexx command>.

* RXS <command> - This commands executes the ARexx string file named in <command>.

* SYSTEM <command> - This commands executes the AmigaDOS command named in <command>.

* QUIT - When AmigaGuide encounters this command is shuts down the current database.

== A Working Database ==

As an example, Let's make the text file below into a simple AmigaGuide database. The simple database will consists of a single node.

<nowiki> What is a user interface? This sweeping phrase covers all
aspects of communication between the user and the computer. It
includes the innermost mechanisms of the computer and rises to
the height of defining a philosophy to guide the interaction
between human and machine. Intuition is, above all else, a
philosophy turned into software. See the Amiga ROM Kernel
Reference Manual: Libraries for more information.

Intuition screens are the basis of any display Intuition can
make. Screens determine the fundamental characteristics of the
display such as the resolution and palette and they set up the
environment for multiple, overlapping windows that makes it
possible for each application to have its own separate visual
context.

Windows are rectangular display areas that open on screens.
The window acts as a virtual terminal allowing a program to
interact with the user as if it had the entire display all to
itself. Windows are moveable and can be positioned anywhere
within the screen on which they exist. Windows may also have a
title and borders containing various gadgets for controlling
the window.

Gadgets are software controls symbolized by an image that the
user can operate with the mouse or keyboard. They are the
Amiga's equivalent of buttons, knobs and dials.

Menus are command and option lists associated with an
application window that the user can bring into view at any
time. These lists provide the user with a simple way to access
features of the application without having to remember or enter
complex character-based command strings.</nowiki>

If AmigaGuide displayed the file above, it would appear without any buttons linking it to text files or databases. To mark this file as an AmigaGuide database, add the @DATABASE command. As mentioned earlier, it must start on the first line in the first column of the file.

Since there will be no index for this database, the next command can be a @NODE. For AmigaGuide to open a database, it must contain a node. Since this will be the first node in the database, it should be named MAIN.

At the bottom of the file, on a separate line, add the @ENDNODE command. This tells AmigaGuide that the current node ends here. All nodes must contain an @ENDNODE command.

This is what we have so far:

@DATABASE
@NODE MAIN
What is a user interface? This sweeping phrase covers all
.
.
.
complex character-based command strings.
@ENDNODE

The file is now an AmigaGuide database. However, since the database has only one node and has no link points, the database will still appear as plain text. Also, AmigaGuide will ghost all of the navigation buttons. The database can be broken into smaller nodes if desired. Normally such a short file would not need to be broken up, but it makes a good example.

One important issue to consider while designing an AmigaGuide database is how to lay it out. Some thought should go into the break-up of a document into manageable nodes, and how these nodes relate--and eventually link--to one another. Each node should consist of information dealing with one topic and should contain links to other related nodes.

Notice that the example text is about Intuition, but each paragraph discusses a different topic of Intuition. The first paragraph is an overview followed by four paragraphs: one each on screens, windows, gadgets and menus. This organization makes it convenient to make each paragraph a node with a table of contents in the beginning:

<nowiki> Intuition Table of Contents

Introduction
Screens
Windows
Gadgets
Menus</nowiki>

Since the Table of Contents node is first, it is the MAIN node. The other paragraphs follow the MAIN node, each in their own separate node. So as not to confuse AmigaGuide, each node within a database must have a different name.

<nowiki> @DATABASE
@NODE MAIN "Intuition Table of Contents"
Introduction
Screens
Windows
Gadgets
Menus
@ENDNODE

@NODE Intro "Introduction"
What is a user interface? This sweeping phrase...
@ENDNODE

@NODE Screen "Screens"
Intuition screens are the basis of any display...
@ENDNODE

@NODE Window "Windows"
Windows are rectangular display areas that open...
@ENDNODE

@NODE Gadget "Gadgets"
Gadgets are software controls symbolized by an...
@ENDNODE

@NODE Menu "Menus"
Menus are command and option lists associated...
@ENDNODE</nowiki>

When AmigaGuide loads the database above, AmigaGuide displays the MAIN node with the title string Intuition Table of Contents in the window's title bar. As the user clicks the Browse buttons at the top of the AmigaGuide window, AmigaGuide steps through each node in the database, displaying each paragraph. Notice that each node in the database uses the window title parameter. As the Browse buttons step through the database displaying the different nodes in sequence, the AmigaGuide window title changes to match the title from the current node.

An important limitation of the database above is the only way to access the different nodes is using the ``Browse'' button to step through them in the order they appear in the database. The database still has no buttons within the nodes to link to other nodes.

== Using Link Points ==

The link point command is probably the most commonly used command in a database. With it you can make a word in one node reference another node. For example, in the Table of Contents node from the previous example, you can make each entry from the table into a button that references its respective node.

The template for a link point is:

@{<label> <action command>}

The label parameter is the word or phrase in a database that is made into a button, and the action command is the action AmigaGuide takes when the user clicks the button. For our example, we want each topic in the table of contents to be a label and the action command for each to be a LINK command. The LINK command loads and displays another node.

@{<label> LINK <name> <line#>}

For example, if you change the word Introduction from the Table of Contents node into a link point it would look like this:

@{"Introduction" LINK Intro}

The <label> string must be in quotes. If you load the database into AmigaGuide after making the change above, the word Introduction would appear as a button on the Table of Contents screen. If the user clicks on the Introduction button, AmigaGuide displays the node named Intro.

Unlike other AmigaGuide commands, link points do not need to start in the first column. This makes it easy to indent a button from the left edge of the window and also to embed a button within a block of text.

Link points can also link to nodes in other databases. As an example, consider the following excerpt from the Intro node:

philosophy turned into software. See the Amiga ROM Kernel Reference
Manual: Libraries for more information.

If an AmigaGuide database of Amiga ROM Kernel Reference Manual: Libraries was readily available, it would be convenient if the word ''Libraries'' from the excerpt was a button, linking the word ''Libraries'' directly to the Libraries manual database. If the Libraries manual database was named Libraries_Manual and it was in the current AmigaGuide path, to make the word Libraries from the Intro node into a link point that opens the Libraries_Manual database, change the excerpt above to the following:

philosophy turned into software. See the Amiga ROM Kernel
Reference Manual: @{"Libraries" LINK Libraries_Manual/Intro} for more information.

In the example above, when the user selects the Libraries button, AmigaGuide will try to display the MAIN node from the database called Libraries_Manual. AmigaGuide will first look for Libraries_Manual in the directory where the example database resides. If it's not there, AmigaGuide searches through its path for the database. Alternately, you can supply a full path name to Libraries_Manual.

A link point can also be used to display a picture. For example, to display an ILBM image of a Workbench screen from the Screen node, use the SYSTEM action command:

@{"Picture of a Workbench Screen" SYSTEM "sys:utilities/Display sys:Workbench.pic"}

From the command above, when the user click the ''Picture of a Workbench Screen'' button, SYSTEM executes the Display utility. Display shows the ILBM file sys:Workbench.pic. Because Display is merely a shell command, you can substitute your own ILBM viewer for Display.

Below is the finished database with a few more interactive link points.

<nowiki> @DATABASE
@NODE MAIN "Intuition Table of Contents"
@{"Introduction" LINK Intro}
@{"Screens" LINK Screen}
@{"Windows" LINK Window}
@{"Gadgets" LINK Gadget}
@{"Menus" LINK Menu}
@ENDNODE

@NODE Intro "Introduction"
What is a user interface? This sweeping phrase covers all
aspects of communication between the user and the computer. It
includes the innermost mechanisms of the computer and rises to
the height of defining a philosophy to guide the interaction
between human and machine. Intuition is, above all else, a
philosophy turned into software. See the Amiga ROM Kernel
Reference Manual: @{"Libraries" LINK Libraries_Manual/Intro} for more information.
@ENDNODE

@NODE Screen "Screens"
Intuition screens are the basis of any display Intuition can
make. Screens determine the fundamental characteristics of the
display such as the resolution and palette and they set up the
environment for multiple, overlapping @{"windows" LINK Window} that makes it
possible for each application to have its own separate visual
context.

@{"Picture of a Workbench Screen" SYSTEM sys:utilities/Display sys:Workbench.pic}

@ENDNODE

@NODE Window "Windows"
Windows are rectangular display areas that open on @{"screens" LINK screen}. The
window acts as a virtual terminal allowing a program to interact
with the user as if it had the entire display all to itself.
Windows are moveable and can be positioned anywhere within the
screen on which they exist. Windows may also have a title and
borders containing various @{"gadgets" LINK Gadget} for controlling the window.
@ENDNODE

@NODE Gadget "Gadgets"
Gadgets are software controls symbolized by an image that the
user can operate with the mouse or keyboard. They are the
Amiga's equivalent of buttons, knobs and dials.
@ENDNODE

@NODE Menu "Menus"
Menus are command and option lists associated with an
application @{"window" LINK Window} that the user can bring into view at any
time. These lists provide the user with a simple way to access
features of the application without having to remember or enter
complex character-based command strings.
@ENDNODE</nowiki>

Although this is a small sample and only a few basic commands are used, it is a good start to making your own AmigaGuide database.

== Troubleshooting ==

To make it easier to create a bug-free database, below is a list of common mistakes made when editing an AmigaGuide database.

As with any type of programming, errors are bound to crop up. One of the most common mistakes is spelling errors. Always double check your spelling of commands. Also, make sure all commands that should begin in the first column do so.

*Symptom: AmigaGuide displays a database as a text file. For example, instead of a button, AmigaGuide displays the link point command that was supposed to display the button.
*Cure: AmigaGuide does not think the file is an AmigaGuide database. Check that the first line of the file is the @DATABASE command and that it starts in the first column.

*Symptom: When displaying a database node, AmigaGuide displays nothing in its window.
*Cure: Either the @ENDNODE command is not present in the node or the @ENDCODE command does not start in the first column.

*Symptom: AmigaGuide does not display a button or its label.
*Cure: The <label> parameter in the link point is missing or not enclosed in quotes.

*Symptom: When the user selects a button, AmigaGuide flashes the screen and displays the error message "Couldn't locate <node>".
*Cure: AmigaGuide cannot locate the node specified in the button's link point command. If the link point command points to a node in another database, the database must be in the AmigaGuide path or the node must contain the full path name to the database. The link point command also require a NODE name as the last parameter in the path separated by a slant (/). If the file is only text and not an AmigaGuide database, its path name should end with '''/MAIN'''. If a node or file has any spaces in its name, the path name must be enclosed within quotes.

*Symptom: AmigaGuide flashes the screen when a button is selected but displays no error message.
*Cure: AmigaGuide does not recognize the <action command> parameter in the link point, or AmigaGuide cannot locate the specified node (see the cure above).

*Symptom: AmigaGuide does not fully display a button.
*Cure: Check that all of the link points end with a closing brace (}). Note that there is a bug in AmigaGuide that can crash the system if a link point does not end with a closing brace.

*Symptom: AmigaGuide will not load a database and displays a "Can't find Node" requester.
*Cure: All databases must contain at least one node. If the file is short, all the text can be in one node called '''MAIN'''. If you do not wish to make the file a database at all, remove the @DATABASE command.

*Symptom: AmigaGuide does not allow the the user to browse the database to its end. It either stops browsing before reaching the last node, or it gets caught in an endless loop, cycling through a number of nodes.
*Cure: At least two nodes within a single database have the same name. Every node must have a different name unless they are in separate databases.

AmigaOS Versions

2021-10-21T07:13:02Z

James Jacobs: Added V46 and V47

The version number reflects a revision of the system software. The chart below lists the specific AmigaOS release versions that system libraries versions correspond to:

{| class="wikitable"
! Version !! Release !! Description
|-
| 27.3 || Kickstart 0.7 || First AmigaOS version shown at Consumer Electronics Show in 1985. This version is obsolete.
|-
| 29 || Kickstart 0.9 || This is an internal AmigaOS version. This version is obsolete.
|-
| 30 || Kickstart 1.0 || This revision is obsolete.
|-
| 31 || Kickstart 1.1 || This was an NTSC only release and is obsolete.
|-
| 32 || Kickstart 1.1 || This was a PAL only release and is obsolete.
|-
| 33 || Kickstart 1.2 || This is the oldest revision of the OS.
|-
| 34 || Kickstart 1.3 || This is almost the same as release 1.2 except it has an Autobooting expansion.library
|-
| 35 || || This is a special RAM-loaded version of the 1.3 revision, except that it knows about the ''A2024'' display modes. No application should need this library unless they need to open an ''A2024'' display mode under 1.3.
|-
| 36 || Kickstart 2.0 || This is the original Release 2 revision that was initially shipped on early ''Amiga 3000'' models.
|-
| 37 || Kickstart 2.04 || This is the general Release 2 revision for all Amiga models.
|-
| 38 || Kickstart 2.1 || This is an updated Release 2 revision for ''Amiga 600'' models.
|-
| 39 || Kickstart 3.0 || This is the original Release 3 revision hat was initially shipped on ''Amiga 1200'' and ''Amiga 4000'' models.
|-
| 40 || Kickstart 3.1 || This is the original Release 3 revision for all Amiga models.
|-
| 41 || Kickstart 3.1 || This is version number which was reserved for the Japanese locale version of AmigaOS 3.1, with multi-byte character support (never completed).
|-
| 42 || || This is version number for some AmigaOS' modules of an internal alpha revision (early 1993).
|-
| 43 || Kickstart 3.2 || This is the original Release 3 revision for Amiga Walker model (never completed). This revision was used for stuff done by/for Amiga Technologies/Amiga International (1995).
|-
| 44 || Kickstart 3.5 || This is an update to Release 3 revision for all Amiga models.
|-
| 45 || Kickstart 3.9 || This is an update to Release 3 revision for all Amiga models.
|-
| 46 || Kickstart 3.1.4 || This is an update to Release 3 revision for all Amiga models.
|-
| 47 || Kickstart 3.2 || This is an update to Release 3 revision for all Amiga models.
|-
| 50 || Kickstart 4.0 || This is the general Release 4 revision for the new ''AmigaOne'' range (Developer PreRelease).
|-
| 51 || Kickstart 4.0 || This is an update to Release 4 revision for the new ''AmigaOne'' range (Official Release from Update 1).
|-
| 52 || Kickstart 4.0 || This is an update to Release 4 revision to include support for PPC equipped classic Amiga models.
|-
| 53 || Kickstart 4.1 || This is an update to Release 4 revision for all supported PPC models.
|}

Wiki Author Credits

2018-11-19T10:55:45Z

James Jacobs: Added missing link

The following is a list of known contributors to this wiki:

* Adam Levin
* Alexandre Balaban
* [http://amigaak.org.nz/ Amiga Auckland]
* Andy Finkel
* Bart Whitebook
* Bill Borsari
* Bill Koester
* Bob Burns
* Bob Pariseau
* Bruce Barrett
* Bryce Nesbitt
* Carl Sassenrath
* Carolyn Scheppner
* Chris Green
* Chris Ludwig
* Chris Raymond
* Dale Luck
* Dan Baker
* [http://gtmooya.blogspot.com/ Daniel Hutchinson]
* Daniel Jedlicka
* Darius Taghavy
* Darren Greenwald
* Dave Berezowski
* Dave Lucas
* David Junod
* David Miller
* Don Cox
* Douglas Stastny
* Eric Cotton
* Ewout Walraven
* Frank Bunton, for his [http://aminet.net/package/docs/help/adosbegin AmigaDOS guide]
* Hans-Joerg Frieden
* [http://amigan.1emu.net/ James Jacobs]
* [http://www.janneperaaho.arkku.net/ Janne Peräaho]
* Jerry Hartzler
* Jez San
* Jim Mackraz
* Joe Katz
* John Orr
* John Wiederhirn
* Karl Churchill
* Ken Farinsky
* Kevin Klop
* Larry Hildenbrand
* Leo Schwab
* [https://sites.google.com/site/takeaprogrammertolunch/ Lyle Hazelwood]
* Mark Barton
* Mark Ricci
* [http://wandel.ca/ Markus Wandel]
* Martin Taillefer
* Michael Sinz
* Nancy Rains
* Neil Kafferkey
* Neil Katin
* Olaf Barthel
* Paul Higginbottom
* Paul Sadlik
* Peter Cherna
* Philippe Ferrucci
* R.J. Mical
* Randell Jesup
* Ray Brand
* Rob Cranley
* Rob Peck
* Rob Wyesham
* Roman Kargin
* Sam Dicker
* Simon Archer
* Spencer Shanson
* Stan Shepard
* Steve Beats
* [http://www.solie.ca Steven Solie]
* Stuart Ferguson
* Susan Deyl
* Thomas Frieden
* Tom Pohorsky
* Tom Rokicki

AmiWest Lesson 8

2013-02-27T06:43:23Z

James Jacobs: Fixed typo

An AmigaOS innovation was the nearly universal support for high level interprocess and scripted communications using "ARexx ports", "ARexx messages" and the interpreted "ARexx" language.

By providing and using ARexx ports, applications are able to send messages to each other. ARexx scripts can also be run by the user or applications providing a level of control that far exceeds simple "recorded" macros found elswhere. As new interpreted languages have been ported to AmigaOS, some - like Python - have been adapted to mimic the ARexx language's ability to send and receive messages.

In this text we will explore the process of having an application to open an ARexx port, send and receive messages and to be able to run ARexx scripts (as application "macros").

==Initialization==

Like much of the current AmigaOS, the support of ARexx operations within C programs has been modernized and simplified using the BOOPSI style of object oriented methods. Under AmigaOS4, the requirements to open specific libraries has been further automated with the OS4 SDK. To use ARexx messaging within an application, we need to initialize a few things:
:* Create a BOOPSI "ARexx Object".
:* Create an hook to a function to receive responses.
:* Create the function called with responses.

===Obtaining an ARexx Object===

After confirming the '''arexx.library''' has been automatically opened, one of the first steps to using ARexx involves calling the BOOPSI '''NewObject''' function. This general BOOPSI function uses the following list of '''tags''' to create an ARexx "object", an ARexx port for your application and get it ready to send/receive messages:

:{| class="wikitable"
|'''Tag Name'''
|style="width: 20%;"|'''Variable Type'''
|'''Required?'''||'''Notes'''
|-
|AREXX_HostName||CONST_STRPTR||Yes, unless Msg Port is used||Sets the "host name" of your application's ARexx port.
|-
|AREXX_NoSlot ||BOOL||No||Determines whether a port counter number is added to the host port name. DEFAULT: FALSE = a number will be appended to the port name.
|-
|AREXX_DefExtension||CONST_STRPTR||No||Filename extension that will get appended when calling a macro script. DEFAULT: "rexx".
|-
|AREXX_Commands||struct ARexxCmd *||Only for receiving commands||A structure containing a table of ARexx commands your application understands. More on this below.
|-
|AREXX_ErrorCode||uint32 *||No||A error code pointer reflecting any issues with creating the new ARexx object.
|-
|AREXX_ReplyHook||struct Hook *||Yes for replies, unless Msg Port is used||A function hook structure for a function that will be called if your app receives a message or reply to a sent message.
|-
|AREXX_MsgPort||struct MsgPort *||No||A message port pointer to be used instead of creating and receiving messages in an ARexx port.
|}

Naturally, how these tags are used will depend on the intended functions of the application. Obviously, an app that will only send messages will not need to define a list of commands received. Some apps might want to set the "AREXX_NoSlot" tag to "TRUE" if they want to make sure they will be the only port with a name and it will require yet more code to handle the possible situation if that port name is already in use. The SDK "autodocs" can provide more detail on these tags.

The following simple code example uses these tags where an application only expects to send ARexx messages:

<syntaxhighlight>
Object *arexx_obj;
STATIC struct Hook reply_hook;
char port_name[40];
uint32 errorCode;
arexx_obj = IIntuition->NewObject(NULL, "arexx.class",
AREXX_HostName, "AREXX_SENDER",
AREXX_NoSlot, TRUE,
AREXX_ErrorCode, &errorCode,
AREXX_ReplyHook, &reply_hook,
TAG_DONE);
</syntaxhighlight>

If the '''NewObject''' function is successful, it will return a pointer to the new ARexx Object. If the function fails, we can check the contents of the "errorCode" variable against these predefined error codes:

:{| class="wikitable"
|RXERR_NO_COMMAND_LIST||||No command list was provided.
|-
|RXERR_NO_PORT_NAME||||No host base name was provided.
|-
|RXERR_PORT_ALREADY_EXISTS||||The class was unable to create a unique name of the base name you provided.
|-
|RXERR_OUT_OF_MEMORY||||Not enough free memory.
|}

===A Reply Hook===

Virtually any application will have incoming messages to deal with. For any message sent, the recipient must send a reply. So a reply hook and function would be used for not only messages sent by other applications, but also responses to messages sent from our application.

To do so, most applications will also define a pointer to an AmigaOS '''Hook''' structure ("reply_hook") to receive incoming messages and responses to sent messages. This standard structure allows us to define a function in our application that will be run when our application receives messages or responses. Once we've successfully obtained an ARexx object giving us an ARexx port, we would set up the hook function like this:

<syntaxhighlight>
STATIC struct Hook reply_hook;
[...]
reply_hook.h_Entry = (HOOKFUNC)reply_callback; // pointer to function name to be called
reply_hook.h_SubEntry = NULL;
reply_hook.h_Data = NULL;
</syntaxhighlight>

In this excerpt, "reply_callback" is the name of a C function we create that will be called when an ARexx message or response is received.

===Reply Function===

While the function we create to be called by the "reply hook" will be passed a number of arguments, we are only concerned with the ARexx message passed to our function. This "RexxMessage" structure has the following basic structure:

<syntaxhighlight>
struct RexxMsg
{
struct Mesage rm_Node; /* Exec message structure */
APTR rm_TaskBlock; /* private global structure */
APTR rm_LibBase; /* private library base */
int32 rm_Action; /* command action code */
int32 rm_Result1; /* primart result (return code) */
int32 rm_Result2; /* secondary result */
STRPTR rm_Args[16]; /* argument block */
}
</syntaxhighlight>

Additional "extension fields" may also be passed within the RexxMessage structure when starting an ARexx program. Those are defined in the CBM AmigaMail articles and CBM "ARexx Programmers Guide".

In most cases, applications passing typical messages will be focused on the two "Result" fields. The first value ("Result1") will contain an integer where zero means there was no error or it will have an error code number (>0). In the cases where there is no error, the second field ("Result2") will contain a pointer to any result string sent with the message (or zero if none).

The following is an example of a simple implementation of a reply function that just prints out the contents of received messages:

<syntaxhighlight>
STATIC VOID reply_callback(struct Hook *hook UNUSED, Object *o UNUSED, struct RexxMsg *rxm)
{
IDOS->Printf("Result1 =>%ld<\n", rxm->rm_Result1);
if (rxm->rm_Result1 == 0)
IDOS->Printf("Result2 =>%s<\n", (CONST_STRPTR)rxm->rm_Result2);
}
</syntaxhighlight>

==Sending ARexx Messages==

Once we have initialized a BOOPSI ARexx Object and the reply_hook structure, we are then ready to try to send ARexx messages. Of course, sending messages can be broken into a few steps:

:* Finding the ARexx port to send the message to.
:* Sending the ARexx message.
:* Waiting for a response to our message.
:* Handling the response.

===Finding the Target Port===

To send a message, you have to have a valid name of the target ARexx message port. With the port name in a string, we can use the AmigaOS '''FindPort''' function to determine if the port exists. To prevent ports from appearing or disappearing during this search, calling '''FindPort''' is "wrapped" with '''Forbid'''/'''Permit''' functions to interupt multitasking. Obvbiously, this interuption should be kept as short as possible.

The following code excerpt would search for the Workbench ARexx port:

<syntaxhighlight>
CONST_STRPTR port_name = "WORKBENCH";
IExec->Forbid();
if (IExec->FindPort(port_name))
{
Exec->Permit();
IDOS->Printf("Found WORKBENCH ARexx port!\n");
// Here we can go on to send a message.
}
else
{
Exec->Permit();
IDOS->Printf("WORKBENCH ARexx port not found.\n");
}
</syntaxhighlight>

As you can see, we make sure to reenable multitasking as quickly as possible, regardless of whether the port name was found. As with any error trapping, any application should have a graceful way of handling an issue like a missing ARexx port and letting the user deal with the occurence.

===Sending the Message===

After all our steps of initialization and verifying our target ARexx port, sending our ARexx message is a single call of the BOOPSI '''IDoMethod''' function. With the "AM_EXECUTE" method, the '''IDoMethod''' function uses the ARexx object, the method name and the following parameters:

:{| class="wikitable"
|'''Argument Name'''
|style="width: 20%;"|'''Variable Type'''
|'''Notes'''
|-
|MethodID||uint32||The arexx class "method", in this case "AM_EXECUTE".
|-
|ape_CommandString||CONST_STRPTR||The command and arguments to be executed - either sent to an ARexx port or the ARexx host.
|-
|ape_PortName||CONST_STRPTR||The name of the ARexx port to send the message to, if not the ARexx host.
|-
|ape_RC||int32 *||Primary result code if the message was sent to the ARexx host.
|-
|ape_RC2||uint32 *||Secondary result code if the message was sent to the ARexx host.
|-
|ape_Result||STRPTR *||The result string if the message was sent to the ARexx host.
|-
|ape_IO||BPTR||Alternate IO channel pointer if an executed script is to use a different IO channel.
|}

To read more about these parameters, refer to the "arexx_cl" autodocs.

To send a message, we only need to add the target port name and our message string, as follows:

<syntaxhighlight>
CONST_STRPTR cmd = "HELP";
int32 RC,RC2;
char result[100];
IIntuition->IDoMethod(arexx_obj,AM_EXECUTE,cmd,port_name,NULL,NULL,NULL,NULL);
</syntaxhighlight>

As you can see all the return & result arguments are given NULL's when we send an ARexx message. Sending ARexx messages is considered "Asynchronous" - in other words, our application will not get an immediate response and will continue operating in the meantime.

===Waiting for and Handling Replies===

When a response to our sent message is received, it will arrive with an AmigaOS '''signal''' to our application's message port that it has received an ARexx message. Like many other signals to applications (Intuition, control code signals, etc.) we need to obtain a mask for receiving ARexx events. Then we can combine all those signals together and call the '''Wait''' function to put our app asleep, waiting for those events.

When an event matching any of the '''Wait''' function's set of signals occurs, our application will be woken up. Then we have to determine if it was ARexx message that woke up our app and handle that event. At that point, we use the BOOPSI "IDoMethod" function again, this time with the "AM_HANDLEEVENT" method. This will cause the reply_hook & function (defined above) to be called to handle the incoming message.

Here is some example code of waiting for handling an incoming ARexx message:

<syntaxhighlight>
uint32 rxsig = 0, signal;
IIntuition->GetAttr(AREXX_SigMask, arexx_obj, &rxsig);
signal = IExec->Wait(rxsig | SIGBREAKF_CTRL_C);
if (signal & rxsig)
{
IIntuition->IDoMethod(arexx_obj, AM_HANDLEEVENT);
}
</syntaxhighlight>

As configured, this '''Wait''' function will put our application to sleep until it receives either an ARexx message or "control-c" signal. Of course, a complete application would also check for and respond to a possible "control-c" signal (or anything else) and respond accordingly.

==Receiving ARexx Messages==

Creating an application for receiving designated ARexx commands is handled in a similar fashion as dealing with replies to sent messages (above), except the "known" commands are defined in the application code and a function is designated to be called when each of those commands is received.

To start with, if we are create an application meant to receive ARexx commands then we will have to adjust our '''NewObject''' request for a new ARexx Object. In this case, that code might look like:

<syntaxhighlight>
arexx_obj = IIntuition->NewObject(NULL, "arexx.class",
AREXX_HostName, "AREXX-RECEIVER",
AREXX_NoSlot, TRUE,
AREXX_ErrorCode, &errorCode,
AREXX_Commands, Commands,
AREXX_NoSlot, TRUE,
TAG_DONE);
</syntaxhighlight>

The pertinent difference being that we are now defining "AREXX_Command" instead of "AREXX_ReplyHook" in the above sample.

===Defining Commands to be Received===

In an application where we will be receiving a number of predefined commands, we set up an array of structures that will define those commands, the functions to be called when those command are received and what arguments are accepted. Here are the fields used:

:{| class="wikitable"
|'''Field Name''' ||'''Variable Type''' ||'''Notes'''
|-
|ac_Name||CONST_STRPTR||The command name sent. Usually all uppercase.
|-
|ac_ID||uint16||A unique identifier number.
|-
|ac_Func||*()(struct ARexxCmd *, struct RexxMsg *)||A pointer to a function that will be called when this command is received.
|-
|ac_ArgTemplate||CONST_STRPTR||An AmigaDOS style template for the arrguments expected with this command.
|-
|ac_Flags||uint32||Future argument, to be set to NULL now.
|-
|ac_ArgList||uint32 *||With Messages: Result of ReadArgs on arguments received based on template above.
|-
|ac_RC||uint32||With Messages: Primary Result variable.
|-
|ac_RC2||uint32||With Messages: Secondary result variable. This will not be set unless RC > 0.
|-
|ac_Result||STRPTR||With Messages: Result string. This will not be set if RC > 0.
|}

The last four fields of this structure are all set to NULL and zero values when the commands are defined. They will only be used when those commands are used to interact with the incoming message and the sender.

In the follow code sample, you can see where we define just such an array of "ARexxCmd" structures.

<syntaxhighlight>
STATIC struct ARexxCmd Commands[] =
{
{"NAME", 0, rexx_Name, NULL, 0, NULL, 0, 0, NULL},
{"VERSION", 1, rexx_Version, NULL, 0, NULL, 0, 0, NULL},
{"QUIT", 2, rexx_Quit, NULL, 0, NULL, 0, 0, NULL},
{"SEND", 3, rexx_Send, "TEXT/F", 0, NULL, 0, 0, NULL},
{"DATE", 4, rexx_Date, "SYSTEM/S", 0, NULL, 0, 0, NULL},
{"HELP", 5, rexx_Help, NULL, 0, NULL, 0, 0, NULL},
{NULL, 0, NULL, NULL, 0, NULL, 0, 0, NULL}
};
</syntaxhighlight>

As you can see, two of the commands ("SEND" and "DATE") are configured to also accept arguments. The formatting of the "ArgTemplate" field should follow that used by the '''ReadArgs''' function. Please see the autodocs on '''ReadArgs''' for more information on how the template is parsed.

===Waiting for Messages===

The process for waiting for incoming ARexx messages with commands is generally the same as it was in the above example waiting for replies to sent commands. We just obtain the mask ARexx messages, combine it with any other signal masks and call the AmigaOS '''Wait''' function. Again when the application is woken up, we check to see when an ARexx message was received and then call the '''IDoMethod''' with the "AM_HANDLEEVENT" method.

The difference with sent message responses is that when the '''IDoMethod''' function is called with commands, the designated function is called for command received (as set in the Commands array above). For example, if the "SEND" command is received, the "rexx_Send" function will be called.

===Functions to Handle Commands===

When the '''IDoMethod''' function is called with "AM_HANDLEEVENT", the ARexx class will determine which command was received and then call the appropriate function and provide the following arguments:

::STATIC VOID '''<function name>''' (struct ARexxCmd *, struct RexxMsg)

As you can see, the ARexx class passes two structures to the function. The first structure is the same format as that configured in the commands array above and we can use it to read incoming data and send things back to the message sender. The pertinent fields are as follows:

:{| class="wikitable"
|'''Field Name''' ||'''Variable Type''' ||'''Usage'''
|-
|ac_ArgList||uint32 *||An array with the results of ReadArgs filtering the arguments in the sent message. Read these elements to obtain data sent with the message.
|-
|ac_RC||uint32||This argument is the "primary result variable" and is returned to the message sending application to indicate success, warning, errors, etc.
|-
|ac_RC2||uint32||This is the "secondary result variable" and will only be used if the RC variable is set >0.
|-
|ac_Result||STRPTR||This is the "result string" that can be set by our application and will be sent back to the sending app if the above RC variable is = 0.
|}

Typically, "ArgList" entries (like "ArgList[0]") will be read for incoming command parameters. Bear in mind, the contents of those arguments are parsed and filtered by the '''ReadArgs''' function using the template set in the commands array, as a command line would be. Please see the autodocs on '''ReadArgs''' for more information on how the template is parsed and what results are provided.

An example of a simple function for the "SEND" command entry above could look like this:

<syntaxhighlight>
STATIC VOID rexx_Send(struct ARexxCmd *ac, struct RexxMsg *rxm UNUSED)
{
IDOS->Printf(" Received SEND ARexx message.\n");
IDOS->Printf(" with this text:\n");

// Print the text received from the message sender
if (ac->ac_ArgList[0])
IDOS->Printf(" %s\n", (CONST_STRPTR)ac->ac_ArgList[0]);
}
</syntaxhighlight>

When the command function is finished, the contents of the three "result" parameters are returned to the sending application. The primary result variable "ac_RC" indicates command success and which of the other two variables are returned to the sending application. If RC=0, then the result string "ac_Result" is sent back to the sending application. If RC>0, then the secondary result variable "ac_RC2" is returned.

==Running ARexx Script Macros==

Besides simply sending ARexx messages between applications, ARexx provides a complete programming language that can be used to create "scripts" that an application can call and run as "macros".

===Call the ARexx Script===

To call an ARexx script from within your program, we go through the same initialization as for sending ARexx messages - create an ARexx object, define a reply hook, and then call a simple variation of the '''IDoMethod''' function. When calling '''IDoMethod''', instead of providing a command name and target message port name, we provide the name of the ARexx script and allow the port name field to default to the ARexx host. When the '''IDoMethod''' is called, the ARexx host finds and runs the designated script. Here is an example of such a call:

<syntaxhighlight>
IIntuition->IDoMethod(arexx_obj, AM_EXECUTE, "rx_me_demo.rexx", NULL, NULL, NULL, NULL, NULL);
</syntaxhighlight>

As when sending messages, all the return fields are set to NULL. Just like sending a message, running an ARexx macro is another "asynchronous" function and any feedback will be sent back to our application using an AmigaOS '''signal'''. And so the process of dealing with script results is the same: the application obtains an Arexx signal mask, uses '''Wait''' function to wait for a response and calls '''IDoMethod''' with the "AM_HANDLEEVENT" method if an ARexx signal was received. Finally, results from a called script are sent via a reply message, the reply hook is engaged and the designated reply function called.

===Receiving Script Output===

When the script finishes, the reply function is called and the output from the script is provided in the "RexxMsg" structure in the following arguments:

:{| class="wikitable"
|'''Field Name''' ||'''Variable Type''' ||'''Usage'''
|-
|rm_Result1||uint32||This argument is the "primary result variable" and indicates success, warning, errors, etc. of calling the script. If Result1 = 0 there was no error; 5=warning, 10=error & 20=severe error.
|-
|rm_Result2||uint32||This argument is either the error code or pointer to the result string from the script, depending on Result1. If Result1=0, Result2 is a STRPTR; if Result1>0, Result2 is the error number.
|}

===The ARexx Script===

An ARexx script called by an application can perform a vareity of functions - to interact with the user, to send commands back to the program that called it and/or to interact with other applications via ARexx messages. As a simple scripting language, these are also things that can be added or modified by more experienced users providing a powerful way to extend the functionality of an application.

The simplest way to send output back to the calling application is to provide a string with the ARexx '''return''' function at the end of the script. With the primary result ("Result1") equal to zero, the secondary result variable ("Result2") will point to that output string.

With a more sophisticated application, a script could send its own ARexx commands back to our application, thereby automating operations. By default, an ARexx script run by an application is pre-configured to address the port of the application, so it's easy to send messages back to the calling application.

==Closing Down ARexx Messaging==

Once an application is finished and ready to close down its ARexx port, it is simply a matter of calling the '''DisposeObject''' function. This will remove the application's ARexx port and deallocate all related resources, like this:

<code><pre>
IIntuition->DisposeObject(arexx_obj);
</pre></code>

In case there may still be ARexx messages coming in or which haven't been handled, the "AM_FLUSH" method can be used with '''IDoMethod''' to clear them out ''before'' disposing the ARexx object, like this:

<code><pre>
IIntuition->IDoMethod(arexx_obj, AM_FLUSH);
</pre></code>

= Examples =

To download example code click [[Media:ARexxExamples.lha|on this link]].

==EXAMPLE ONE: Sending ARexx Messages==

The followig is a demonstration program for sending ARexx messages from an application.

This example opens an ARexx port called "AREXX-SENDER", asks the user for the name of a port and a text to send to that port. It is most easily tested by addressing the "WORKBENCH" port (it's almost always there and waiting) and sending it a "HELP" message.

<syntaxhighlight>
/*
************************************************************
**
** Created by: Paul Sadlik
** CodeBench 0.23 (17.09.2011)
**
** Project: ARexx-Sender
**
** Version: 4
**
** An exmple of how to send AN ARexx message from an AmigaOS4
** C program using OS4's arexx.class.
**
** Date: 02-01-2012 09:19:17
**
************************************************************
*/

#include <string.h>
#include <stdio.h>
#include <classes/arexx.h>

#include <proto/exec.h>
#include <proto/intuition.h>
#include <proto/dos.h>
#include <proto/arexx.h>

// Proto for the reply hook function
STATIC VOID reply_callback(struct Hook *, Object *, struct RexxMsg *);

// Declare our reply hook function static variable
STATIC struct Hook reply_hook;

// Starting program
int main(void)
{
/*
* DECLARE VARIABLES
*/

// Declare an Object variable for our ARexx object
Object *arexx_obj;

// Declare string variable to be used for the port message will be sent to
char port_name[40];

// Declare string variable for command to sent in ARexx message
char cmd[40];

// ARexx error code pointer
uint32 errorCode;

/*
* INITIALIZE & OPEN AREXX CLASS
*/

// Check whether ARexx library has been opened
// (opened automatically when compiled with the -lauto option)
if (!ARexxBase)
{
printf(" ARexx not library opened\n");
return RETURN_FAIL;
}
printf(" ARexx library opened\n");

// open ARexx class object (creates port) - see autodocs ATTRIBUTES list
arexx_obj = IIntuition->NewObject(NULL, "arexx.class",
AREXX_HostName, "AREXX-SENDER", // you must set an ARexx port name for this app
AREXX_NoSlot, TRUE, // set whether name should be incremented
AREXX_ErrorCode, &errorCode, // set variable to receive error code, if any
AREXX_ReplyHook, &reply_hook, // the hook structure defines how replies will be handled
TAG_DONE);

// if ARexx class was successfuly opened, continue
if (arexx_obj)
{
// Define ReplyTo hook structure - to set which function gets called when a reply is received
printf(" set up ReplyTo hook\n");
reply_hook.h_Entry = (HOOKFUNC)reply_callback; // pointer to function name to be called
reply_hook.h_SubEntry = NULL;
reply_hook.h_Data = NULL;

/*
* GET INPUT FROM USER
*/

// Ask user for name of port to send message to
printf("Please enter the UPPERCASE name of an ARexx port to send a message to.\n");
fgets(port_name,sizeof(port_name),stdin);
port_name[strlen(port_name)-1] = '\0'; // strip \n off end of string
printf(" Got ARexx port name =>%s<\n",port_name);

// Ask user for message to send - some command the host will accept
printf("Please enter a message to send.\n");
fgets(cmd,sizeof(cmd),stdin);
cmd[strlen(cmd)-1] = '\0'; // strip \n off end of string
printf(" Got ARexx message =>%s<\n",cmd);

/*
* SEND AREXX MESSAGE
*/

// check whether target message port is found
// (FindPort must be enclosed in a Forbid/Permit pair)
IExec->Forbid();
if (IExec->FindPort(port_name))
{
// target message port found, send message
IExec->Permit();
printf(" sending ARexx message\n");
IIntuition->IDoMethod(arexx_obj, AM_EXECUTE,cmd,port_name, NULL, NULL, NULL, NULL);
printf(" ARexx message sent, waiting for reply\n");

/*
* WAIT FOR HOST TO REPLY TO MESSAGE
*/

// Obtain wait mask for arexx class
ULONG rxsig = 0, signal;
IIntuition->GetAttr(AREXX_SigMask, arexx_obj, &rxsig);

// Call Wait command to wait for reply to our sent message
signal = IExec->Wait(rxsig | SIGBREAKF_CTRL_C);
printf(" Program received some message...\n");

/*
* HANDLE RESPONSE
*/

// Did we receive an ARexx event ?
if (signal & rxsig)
{
printf(" ARexx message received... handling...\n");

// Handling the incoming event will cause the reply_hook function to get called
IIntuition->IDoMethod(arexx_obj, AM_HANDLEEVENT);
printf(" ARexx message handled!\n");
}

// Did the user pressed Control-C ?
if (signal & SIGBREAKF_CTRL_C)
{
printf(" Received CTRL-C message.\n");
}
}
else
{
// target message port not found
IExec->Permit();
printf(" Unable to send ARexx message, port name not found..\n");
}

/*
* DISPOSE OF AREXX CLASS OBJECT
*/
printf(" Disposing of ARexx object.\n");
IIntuition->DisposeObject(arexx_obj);

}
else
{
IDOS->Printf(" Could not create the ARexx object.\n");
if (errorCode == RXERR_PORT_ALREADY_EXISTS)
IDOS->Printf(" Port already exists.\n");
}
printf(" Quitting... GOODBYE!.\n");
return RETURN_OK;
}

/* reply_callback FUNCTION
*
* This function gets called whenever we get an ARexx reply and then call the "AM_HANDLEEVENT"
* arexx class method. In this example, we will see a reply come back from the REXX host when
* it has finished with the command we sent.
*/
STATIC VOID reply_callback(struct Hook *hook UNUSED, Object *o UNUSED, struct RexxMsg *rxm)
{
printf(" HOOK FUNCTION RUNNING...\n");

/*
* DISPLAY CONTENTS OF REPLY MESSAGE
*/

// Show primary result code (integer) - 0 = success, no error
printf(" Result1 =>%ld<\n",rxm->rm_Result1);

// display secondary result - succesful or an error code
if (rxm->rm_Result1 == 0)

// if result code is 0, display any result string sent back
printf(" Result2 =>%s<\n",(STRPTR)rxm->rm_Result2);

else

// if result code > 0, display error code number
printf(" Result2 =>%ld<\n",rxm->rm_Result2);
}
</syntaxhighlight>

==EXAMPLE TWO: Receiving ARexx Command Messages==

The following is a demonstration of an application that can receive a number of ARexx command messages.

This program first declares a "Commands" array that spells out what ARexx commands it will receive, how they are formatted and what functions to call. The program next goes through the typical steps of initializing ARexx and opening an ARexx port called "AREXX-RECEIVER". Then it enters a loop - waiting for incoming messages until it receives a "QUIT" command. Finally, there are functions for each command that the application accepts.

The program from Example One can be used to send commands to this program.

<syntaxhighlight>
/*
************************************************************
**
** Created by: Paul Sadlik
** CodeBench 0.23 (17.09.2011)
**
** Project: ARexx-Receiver
**
** Version: 4
**
** An example of how to receive ARexx messages with an AmigaOS4
** C program using OS4's arexx.class.
**
** Date: 27-11-2011
**
** Version: v2
**
************************************************************
*/

#include <string.h>
#include <stdio.h>
#include <classes/arexx.h>
#include <utility/utility.h>

#include <proto/exec.h>
#include <proto/intuition.h>
#include <proto/dos.h>
#include <proto/utility.h>
#include <proto/arexx.h>

// Protos for the ARexx command functions to be called when our commands are received
STATIC VOID rexx_Name (struct ARexxCmd *, struct RexxMsg *);
STATIC VOID rexx_Version(struct ARexxCmd *, struct RexxMsg *);
STATIC VOID rexx_Quit (struct ARexxCmd *, struct RexxMsg *);
STATIC VOID rexx_Send (struct ARexxCmd *, struct RexxMsg *);
STATIC VOID rexx_Date (struct ARexxCmd *, struct RexxMsg *);
STATIC VOID rexx_Help (struct ARexxCmd *, struct RexxMsg *);

/*
* DECLARE COMMANDS RECOGNIZED BT THIS AREXX HOST
*/

const uint8 NoOfCmds = 6;
//uint8 NoOfCmds;

// Declare the array of structure that defines all the functions, parameters, etc.
// of the commands that are valid for this program. (This array must neve
// be const because arexx.class writes into it). See the "AREXX_Commands"
// description in arexx_cl autodocs.
STATIC struct ARexxCmd Commands[] =
{
{"NAME", 0, rexx_Name, NULL, 0, NULL, 0, 0, NULL},
{"VERSION", 1, rexx_Version, NULL, 0, NULL, 0, 0, NULL},
{"QUIT", 2, rexx_Quit, NULL, 0, NULL, 0, 0, NULL},
{"SEND", 3, rexx_Send, "TEXT/F", 0, NULL, 0, 0, NULL},
{"DATE", 4, rexx_Date, "SYSTEM/S", 0, NULL, 0, 0, NULL},
{"HELP", 5, rexx_Help, NULL, 0, NULL, 0, 0, NULL}
};

// declare string buffer pointer to be used for creating HELP msg response
STRPTR buffer = NULL;

// Declare/define a global variable that we're running
BOOL running = TRUE;

// ARexx error code pointer
uint32 errorCode;

// Starting program
int main(void)
{
// Declare an Object variable for our ARexx object
Object *arexx_obj;

/*
* INITIALIZE & OPEN AREXX CLASS
*/

// Check whether ARexx library has been opened
// (opened automatically when compiled with the -lauto option)
if (!ARexxBase)
{
printf(" ARexx not library opened\n");
return RETURN_FAIL;
}
printf("ARexx library opened\n");

// open ARexx class object (creates port) - see autodocs ATTRIBUTES list
arexx_obj = IIntuition->NewObject(NULL, "arexx.class",
AREXX_HostName, "AREXX-RECEIVER", // set an ARexx port name for this app
AREXX_NoSlot, TRUE, // set whether name should be incremented
AREXX_ErrorCode, &errorCode, // set variable to receive error code, if any
AREXX_Commands, Commands, // provide structure of commands recognized by app
AREXX_NoSlot, TRUE, // set to not number port name (there can only be one)
TAG_DONE);

// if ARexx class was successfuly opened, continue
if (arexx_obj)
{
printf("ARexx port opened\n");

// Determine the number of commands
//NoOfCmds = (sizeof(Commands)/sizeof(ARexxCmd)) -1;

// Obtain wait mask for arexx class
ULONG rxsig = 0, signal;
IIntuition->GetAttr(AREXX_SigMask, arexx_obj, &rxsig);

/*
* START EVENT LOOP
*/

// continue loop until "running" variable is FALSE
do
{
// Wait for incoming messages from Intution
signal = IExec->Wait(rxsig | SIGBREAKF_CTRL_C);
printf("Program received some message...\n");

// Did we receive an ARexx event ?
if (signal & rxsig)
{
/*
* HANDLE INCOMING MESSAGE
*/
printf("ARexx message received... handling...\n");

// "Handling" the incoming event will cause command functions to get
// called as defined in the "Commands" structure above.
IIntuition->IDoMethod(arexx_obj, AM_HANDLEEVENT);
printf("ARexx message handled!\n");
}

// Did the user pressed Control-C (a.k.a., "Break") ?
if (signal & SIGBREAKF_CTRL_C)
{
printf("Received CTRL-C message.\n");

// set "running" to quit event loop
running = FALSE;
}
}
while (running);

/*
* CLEAR OUT ANY AREXX MESSAGES
*/
IIntuition->IDoMethod(arexx_obj, AM_FLUSH);

/*
* DISPOSE OF AREXX CLASS OBJECT
*/
printf("Disposing of ARexx port.\n");
IIntuition->DisposeObject(arexx_obj);

// free any memory used by HELP response string buffer
if (buffer)
IExec->FreeVec(buffer);

}
else
{
IDOS->Printf(" Could not create the ARexx object.\n");
if (errorCode == RXERR_PORT_ALREADY_EXISTS)
IDOS->Printf(" Port already exists.\n");
}

printf("Quitting... GOODBYE!.\n");
return RETURN_OK;
}

/*
* rexx_Name FUNCTION
*
* This function gets called when the "NAME" command is received and the
* "AM_HANDLEEVENT" arexx class method called.
*
* This function simply returns this program's name.
*/
STATIC VOID rexx_Name(struct ARexxCmd *ac, struct RexxMsg *rxm UNUSED)
{
printf(" Received NAME ARexx message.\n");

// return the program name to the message sender
ac->ac_Result = (STRPTR) "ARexxReceiver";
}

/*
* rexx_Version FUNCTION
*
* This function gets called when the "VERSION" command is received and the
* "AM_HANDLEEVENT" arexx class method called.
*
* This function simply returns this program's version number.
*/
STATIC VOID rexx_Version(struct ARexxCmd *ac, struct RexxMsg *rxm UNUSED)
{
printf(" Received VERSION ARexx message.\n");

// return the program version to the message sender
ac->ac_Result = (STRPTR) "4.0";
}

/*
* rexx_Quit FUNCTION
*
* This function gets called when the "QUIT" command is received and the
* "AM_HANDLEEVENT" arexx class method called.
*
* This function will cause this program to exit its event loop and quit.
*/
STATIC VOID rexx_Quit(struct ARexxCmd *ac, struct RexxMsg *rxm UNUSED)
{
printf(" Received QUIT message.\n");

// Respond that this app is quitting
ac->ac_Result = (STRPTR) "ARexxReceiver quitting...";

// Set "running" to quit the main event loop
running = FALSE;
}

/*
* rexx_Send FUNCTION
*
* This function gets called when the "SEND" command is received (with text
* to be printed) and the "AM_HANDLEEVENT" arexx class method called.
*
* This function will print the received text to the console.
*/
STATIC VOID rexx_Send(struct ARexxCmd *ac, struct RexxMsg *rxm UNUSED)
{
printf(" Received SEND ARexx message.\n");
printf(" with this text:\n");

// Print the text received from the message sender
if (ac->ac_ArgList[0])
printf(" %s\n", (STRPTR)ac->ac_ArgList[0]);
}

/*
* rexx_Date FUNCTION
*
* This function gets called when the "DATE" command is received and the
* "AM_HANDLEEVENT" arexx class method called.
*
* Without any parameters this command will get a response of this program's
* compilation date. With the "SYSTEM" parameter, the response will be the
* current system date.
*/
STATIC VOID rexx_Date(struct ARexxCmd *ac, struct RexxMsg *rxm UNUSED)
{
printf(" Received DATE ARexx message.\n");
// is the SYSTEM switch specified with the received command message?

if (!ac->ac_ArgList[0])
{
// return the compilation date.
printf(" with no parameters - returning compile date.\n");
ac->ac_Result = (STRPTR) "1-21-12";
}
else
{
// compute system date and store in systemDate buffer
printf(" with SYSTEM parameter - returning system date.\n");

// declare the needed variables
STATIC TEXT systemDate[LEN_DATSTRING];
struct DateTime dt;

// get the system date
IDOS->DateStamp(&dt.dat_Stamp);

// set datetime struct to format output
dt.dat_Format = FORMAT_USA;
dt.dat_Flags = 0;
dt.dat_StrDay = NULL;
dt.dat_StrDate = systemDate;
dt.dat_StrTime = NULL;

// get string with date
IDOS->DateToStr(&dt);

// return string with system date
ac->ac_Result = systemDate;
}
}

/*
* rexx_Help FUNCTION
*
* This function gets called when the "HELP" command is received and the
* "AM_HANDLEEVENT" arexx class method called.
*
* This function will build a list of all the commands this program is
* defined to handle and will return a comma separated list to the message
* sender.
*/
STATIC VOID rexx_Help(struct ARexxCmd *ac, struct RexxMsg *rxm UNUSED)
{
uint16 cmd_no = 0;
printf(" Received HELP ARexx message.\n");

// loop though the commands array, accumulating commands list
for(cmd_no = 0; cmd_no < NoOfCmds; ++cmd_no)
{
if (cmd_no == 0)
{
// try to add command name to empty string buffer
buffer = IUtility->ASPrintf("%s",Commands[cmd_no].ac_Name);
if (buffer==NULL)
break;
}
else
{
// try to add command name to accumulating string buffer
buffer = IUtility->ASPrintf("%s, %s",buffer,Commands[cmd_no].ac_Name);
if (buffer==NULL)
break;
}
}

//done looping through commands - do we have a list?
if (buffer==NULL)
{
printf(" unable to build commands list.\n");
// return list of accepted commands to ARexx message sender
ac->ac_Result = (STRPTR) "Unable to build commands list";
}
else
{
printf(" command list = >%s<\n",buffer);
// return list of accepted commands to ARexx message sender
ac->ac_Result = buffer;

// NOTE: memory allocated for buffer will be freed at end of main func
}
}
</syntaxhighlight>

==EXAMPLE THREE: Calling ARexx Scripts==

This application and ARexx script demonstrate a simple case where an application can run an ARexx script and receive results from it.

===The Application===

This program follows the pattern of Example One above except that it causes an ARexx script to be run instead of sending an ARexx message. Like Example one, it waits for a response and ARexx results are handled by a reply function.

<syntaxhighlight>
/*
************************************************************
**
** Created by: Paul Sadlik
** CodeBench 0.23 (17.09.2011)
**
** Project: ARexx-Macro
**
** Version: 2
**
** An exmple of how to call an ARexx macro script from an
** AmigaOS4 C program using OS4's arexx.class.
**
** Date: 27-11-2011
**
************************************************************
*/

#include <stdio.h>
#include <classes/arexx.h>

#include <proto/exec.h>
#include <proto/intuition.h>
#include <proto/dos.h>
#include <proto/arexx.h>

// Proto for the reply hook function.
STATIC VOID reply_callback(struct Hook *, Object *, struct RexxMsg *);

// Declare our reply hook function static variable
STATIC struct Hook reply_hook;

// Starting program
int main(void)
{
/*
* DECLARE VARIABLES
*/

// Declare an Object variable for our ARexx object
Object *arexx_obj;

/*
* INITIALIZE & OPEN AREXX CLASS
*/

// Check whether ARexx library has been opened
// (opened automatically when compiled with the -lauto option)
if (!ARexxBase)
{
printf(" ARexx not library opened\n");
return RETURN_FAIL;
}

// open ARexx class object (creates port) - see autodocs ATTRIBUTES list
arexx_obj = IIntuition->NewObject(NULL, "arexx.class",
AREXX_HostName, "AREXX-MACRO", // you must set ARexx port name for this app
// AREXX_Commands, NULL,
AREXX_NoSlot, TRUE, // set it so the port name is not enumerated
AREXX_ReplyHook, &reply_hook, // the hook structure defines how replies will be handled
TAG_DONE);

// if ARexx class was successfuly opened, continue
if (arexx_obj)
{
// Define ReplyTo hook structure - what function gets called when a reply is received
reply_hook.h_Entry = (HOOKFUNC)reply_callback; // pointer to function name to be called
reply_hook.h_SubEntry = NULL;
reply_hook.h_Data = NULL;

/*
* RUN AREXX SCRIPT MACRO
*/

printf("Calling ARexx macro script...\n");
// Run ARexx script in current directory (or REXX: path).
// Results will be returned to the "reply_callback" function.
IIntuition->IDoMethod(arexx_obj, AM_EXECUTE, "rx_me_demo.rexx", NULL, NULL, NULL, NULL, NULL);
printf("Calling macro done.\n");

/*
* WAIT FOR RESPONSE
*/

// Obtain wait mask for arexx class
ULONG rxsig = 0, signal;
IIntuition->GetAttr(AREXX_SigMask, arexx_obj, &rxsig);

// Wait for incoming messages from Intution
signal = IExec->Wait(rxsig | SIGBREAKF_CTRL_C);
printf("Program received some message...\n");

// Did we receive an ARexx event ?
if (signal & rxsig)
{
printf("ARexx message received...\n");

// "Handling" the incoming event will cause the reply_hook function to get called
IIntuition->IDoMethod(arexx_obj, AM_HANDLEEVENT);
printf("ARexx message handled!\n");
}

// Did the user enter a Control-C (a.k.a., "Break") ?
if (signal & SIGBREAKF_CTRL_C)
{
printf("Received CTRL-C message.\n");
}

/*
* DISPOSE OF AREXX CLASS OBJECT
*/
printf("Disposing of ARexx port.\n");
IIntuition->DisposeObject(arexx_obj);
}
else
IDOS->Printf("Could not create the ARexx host.\n");

printf("Quitting... GOODBYE!.\n");
return RETURN_OK;
}

/* reply_callback FUNCTION
*
* This function gets called whenever we get an ARexx reply and then call the "AM_HANDLEEVENT"
* arexx class method. In this example, we will see a reply come back from the REXX host when
* it has finished with the command we sent.
*/
STATIC VOID reply_callback(struct Hook *hook UNUSED, Object *o UNUSED, struct RexxMsg *rxm)
{
printf(" HOOK FUNCTION RUNNING...\n");

/*
* DISPLAY CONTENTS OF REPLY MESSAGE
*/

// Show primary result code (integer) - 0 = success, no error
printf(" Result1 =>%ld<\n",rxm->rm_Result1);

// display secondary result - succesful or an error code
if (rxm->rm_Result1 == 0)

// if result code is 0, display any result string sent back
printf(" Result2 =>%s<\n",(STRPTR)rxm->rm_Result2);

else

// if result code > 0, display error code number
printf(" Result2 =>%ld<\n",rxm->rm_Result2);

}
</syntaxhighlight>

===The Script===

This is a simple ARexx script that addresses the AmigaOS command line ("COMMAND"), it uses "RequestString" to get a string from the user and then it sends that input back to the calling application with the "Return" function.

<pre>
/* Small macro script for the small arexxclass demo */

options results

address COMMAND

cmdline = 'c:requeststring >t:DemoInput "Sample Macro Script" "This is the macro script running!*N*NPlease enter a response message*Nto send back to your app..."'

(cmdline)

if open(handle,"t:DemoInput",'r') then do
input = readln(handle)
call close(handle)
address command 'c:delete T:DemoInput'
end

return input

exit
</pre>

Talk:BOOPSI Popup Menus - Part 1

2012-05-29T04:29:18Z

James Jacobs: Created page with "Can anyone please supply the necessary #defines for the new tags (WINDOW_PopupGadget, etc.)? As matters now stand noone can add this feature to their programs :-("

Can anyone please supply the necessary #defines for the new tags (WINDOW_PopupGadget, etc.)? As matters now stand noone can add this feature to their programs :-(