arexx.class Reference¶
Comprehensive function reference for arexx.class, synthesised from the AmigaOS NDK 3.2 Release 4 (Autodocs/arexx).
This page documents 2 functions of arexx.class. Each function entry follows the canonical autodoc format. struct Name, union Name, enum Name are clickable links to the type definition in the types reference.
Function index¶
arexx_cl()¶
**arexx_cl -- ARexx interface class.
SUPERCLASS
rootclass
DESCRIPTION
This class provides you with a very easy way to implement an ARexx
interface. It will setup a unique ARexx port, start ARexx macros,
parse commands and dispatch command handler functions.
All ARexx class methods and the callbacks you provide it are run in
the context of the task you call ARexx class from. Thus if your
application is a process, DOS is safe to use.
METHODS
OM_NEW -- Passed to superclass first. Creates a new ARexx
interaction object. The message is of type struct opSet *. The
following attributes, communicated in ops_AttrList, are currently
supported, see <classes/arexx.h>:
AREXX_ErrorCode: A ULONG * into which a potential Rexx error
code is placed.
AREXX_HostName: Pointer to a NUL-terminated string, not longer
than 80 characters, of a base port name that
is to be used as public port for ARexx
communication. If AREXX_NoSlot is FALSE, the
class automatically extends the name by a dot
and a number to make it unique.
AREXX_NoSlot: If set, no new port is created, instead a port
of the given name is hijacked or created.
AREXX_ReplyHook: A struct Hook * to a hook that is called
whenever an ARexx message send out by this
class returns.
The hook is called with object = the object
instance of this class and message = the Rexx
message that returned.
AREXX_Commands: Pointer to an array of struct ARexxCmd,
terminated by an ac_Func pointer of NULL, that
defines function names, templates and
callbacks for the ARexx function supported by
the host; see <classes/arexx.h>.
OM_GET -- Retrieves attributes from the class. The message is of type
struct opGet *, with the attribute ID in opg_AttrID. The
following attributes are currently supported:
AREXX_HostName: Returns in opg_Storage a pointer to a NUL-
terminated string providing the host name of
the Arexx communications port.
AREXX_SigMask: Returns in opg_Storage the signal mask to wait
for the arrival of messages on the ARexx host
port.
AREXX_ReplyHook: Returns a struct Hook * of the hook that is
called when a ARexx message send out by the
class has been returned.
OM_DISPOSE -- Closes the port and frees all resources. Passed onto
superclass.
AM_HANDLEEVENT -- Checks for incoming ARexx messages and handles
them. In case the message is a replied message from a ARexx
execution, the AREXX_ReplyHook is called. For incoming commands,
the list of ARexx commands (see AREXX_Commands above) is scanned
for a fitting command, and the corresponding call-back is
executed. If not found, the incomming command is dispatched as a
script to the RexxHost.
AM_FLUSH -- retrieves all pending ARexx commands and ignore them, in
order to shut down the ARexx command port.
AM_EXECUTE -- Executes an ARexx command or macro.
ATTRIBUTES
AREXX_HostName (STRPTR)
The name of the host. The ARexx portname is derived from this.
In pretty much all cases, this should the same as your app's
basename. You should refrain from using names like "MYPROG_RX"
or others with unnecessary suffixes.
To create the portname, the hostname will be uppercased, and,
unless AREXX_NoSlot is specified, a slot number will be
appended.
Applicability is (OM_NEW, OM_GET)
AREXX_NoSlot (BOOL)
Specifies that no slot number should be appended to the port
name when it is being created. This greatly increases the
chances that your requested portname is in use, so your code
must be sure to handle this situation.
Defaults to FALSE.
Applicability is (OM_NEW)
AREXX_DefExtension (STRPTR)
Default filename extension for macros started by your app. Do
not include the ".", just the extension text. In pretty much
all cases, this should be the same as your app's basename. You
should refrain from using extensions like "myrx".
Defaults to "rexx".
Applicability is (OM_NEW)
AREXX_Commands (struct ARexxCmd *)
The table of the commands supported by your ARexx interface.
This will be a pointer to an array of struct ARexxCmd. If this
array is not passed then your host will not be able to process
any ARexx commands.
The following fields must be setup initially by the app before
OM_NEW:
ac_Name (STRPTR)
The name of the command. By convention this is usually all
uppercase, though a case-insensitive comparisons will be
done.
ac_ID (WORD)
A unique number identifying this command.
ac_Func (*()(struct ARexxCmd *, struct RexxMsg *))
A pointer to the function that will be called when this
command is received by your programme. The function will
get past a pointer to its ARexxCmd entry and the RexxMsg
structure received for the command. You may use this
for setting ARexx variables, but please note that is may
be NULL
ac_ArgTemplate (STRPTR)
DOS ReadArgs()-style argument template for this command.
ac_Flags (ULONG)
Command flags. Currently unused, but in order to remain
compatable, you must ensure that this is NULL.
These fields are ignored in OM_NEW and are set by the class
when calling the ac_Func command callback.
ac_ArgList (ULONG *)
Result of ReadArgs() using the arguments received with the
command and ac_ArgTemplate as the template.
ac_RC (LONG)
Primary result, the RC variable. Also causes the RC2
variable to return, and will cause RESULT to NOT be set.
ac_RC2 (LONG)
Secundary result, the RC2 variable. This will not be set
unless RC is non-zero.
ac_Result (STRPTR)
RESULT variable, this should be a string. If you want to
return a number, you will have to convert it to a string
first. This string will not be set if RC is non-zero.
The array must be terminated with a NULL ac_Name field.
Applicability is (OM_NEW)
AREXX_ErrorCode (ULONG *)
A pointer to storage space for OM_NEW to store an error code
when it fails trying to create the object. Possible values
are:
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.
No error code will be returned if you provide a NULL pointer.
Defaults NULL.
Applicability is (OM_NEW)
AREXX_SigMask (ULONG)
The signal mask for the object's message port. This is the
signal you will want to Wait() on so you know when there is
activity at the ARexx port.
Applicability is (OM_GET)
AREXX_ReplyHook (struct Hook *)
This is a function hook that will get called whenever your host
replies to an ARexx message. This generally happens after your
host has sent a message (eg. via AM_EXECUTE) and the task
receiving the message has completed its processing with the
message. This is most useful for checking return codes from
commands sent via AM_EXECUTE.
The object parameter in the hook function will point to the
Object * that is yur host, and the message parameter will be
the ARexx message that is being replied to (from which you
could extract result codes).
Defaults to NULL.
Applicability is (OM_NEW, OM_GET)**
See also
<classes/arexx.h>
Bugs
AREXX_HostName MUST be all uppercase in V40 otherwise the checks for
an already existing port won't work right.
AM_EXECUTE()¶
AM_EXECUTE -- Execute an ARexx macro.
Function
This method allows you to execute a macro in another host. The
default host is the ARexx server. This is how you would execute
disk-based ARexx macros, by passing the name of the file as the
command string to the ARexx server.
This method uses the following custom message structure:
struct apExecute
{
ULONG MethodID;
STRPTR ape_CommandString;
STRPTR ape_PortName;
LONG *ape_RC;
LONG *ape_RC2;
STRPTR *ape_Result;
BPTR ape_IO;
};
ape_CommandString (STRPTR)
This must point to the command including arguments to execute.
If the command is found in the host command list it will be
executed. Unknown commands will be shipped off to the ARexx
server.
ape_RC, ape_RC2, ape_Result (LONG *, LONG *, STRPTR *)
After the command executed you will find the results in here if
the command was one in your host, or if there was a problem
sending the command to the specified host. You will NOT get the
result of the command if it is sent to another host, since the
command is sent asychronously. Use AREXX_ReplyHook for this.
ape_IO (BPTR)
If you execute a script using this method you can pass a pointer
to the IO channel ARexx must use here. This IO channel will be
closed automatically for you after the command executed.
RESULT
As errors are reported in acme_RC and acme_RC2 this method has no
specific return code.