Name
CreateRexxPort -- create a Rexx port for your script (V2.5)
Synopsis
[name$ =] CreateRexxPort(name$[, enum])
Library
amiga

Platforms
AmigaOS and compatibles only

Function
This function will create a Rexx port named name$ for your script. In order to receive ARexx messages, your script needs to have an ARexx port. Other applications can then communicate with your script by sending messages to this port. All messages that arrive at your Rexx port will be forwarded to the callback function which you need to install using the InstallEventHandler() function (use the OnARexx event handler). If you do not install this event handler, you will not get any notifications on incoming messages.

Please remember that Rexx port names are always given in case sensitive notation. Thus, "MYPORT" and "myport" denote two different Rexx ports. For style reasons it is suggested that you use only upper case characters for your port name. Furthermore, each Rexx port must be unique in the system. If you specify a port name which is already in use, this function will fail. Thus, make sure that you use a unique name.

Starting with Hollywood 11, you can set the optional enum argument to True to force CreateRexxPort() to automatically find a vacant Rexx port. It will do this by using the specified name$ and appending numbers like .1, .2, .3... to it until it finds a port name that is still available. This port name will then be returned to you.

Please note that every Hollywood script can only have one ARexx port. Hence, this function can only be called once in your script. You cannot delete the port created by this function. It will be automatically destroyed when Hollywood exits.

An example how to catch ARexx messages is provided below. See InstallEventHandler for more information on how the user callback function will be called.

Inputs
name$
desired name for your Rexx port
enum
optional: True if Hollywood should automatically enumerate Rexx ports until it finds an available one or False if CreateRexxPort() should fail if the specified name is not available (defaults to False) (V11.0)
Results
name$
optional: actual name of the Rexx port; this will only be returned if you have set the enum argument to True (see above) (V11.0)
Example
Function p_EventFunc(msg)
  Switch msg.action
  Case "OnARexx"
    Switch msg.command
    Case "RealFunc"
      Return(100)
    Default
      Local t = SplitStr(msg.args, "\0")
      DebugPrint(msg.command, "called with", msg.argc, "argument(s)")
      For Local k = 1 To msg.argc
         DebugPrint("Argument", k .. ":", t[k - 1])
      Next
    EndSwitch
  EndSwitch
EndFunction
CreateRexxPort("MY_COOL_REXX_PORT_123")
InstallEventHandler({OnARexx = p_EventFunc})
Repeat
  WaitEvent
Forever
Save the code above as a Hollywood script and run it with Hollywood. Then save the following code as a Rexx script and execute it from a Shell with "RX test.rx":
 
/* remember the first line of every Rexx script must be a comment */
OPTIONS RESULTS

/* the port of our Hollywood script is now the host */
ADDRESS MY_COOL_REXX_PORT_123

/* send commands from Rexx to Hollywood and watch the debug output */
DummyFunc_1 '"Dummy Arg 1"'
DummyFunc_2 1 2 3
DummyFunc_3 '"First arg"' '"Second arg"' '"Third arg"'
DummyFunc_4  /* no args */
DummyFunc_5 "These will be handled as separate arguments"
DummyFunc_6 '"This is a single argument (use double quotes!)"'

'RealFunc'
SAY RESULT   /* this will print 100; it is the result from RealFunc */

Show TOC