File: omrexx.txt
Version: 1995-05-15
Author: Christian d'Heureuse
Copyright (C) 1995 Inventec Informatik AG
All rights reserved.



Inventec Object Manager Interface for standard REXX
===================================================

Introduction
------------

This text describes a REXX interface to access software objects.
The software objects that can be accessed with this interface are
written in C++ and are built based on the Inventec general object
manager interface. The general object manager interface is a
technology for portable object-oriented software development.
There will be object manager mapping layers for object environments
like OLE, SOM and Corba in the future. This text describes the
mapping layer (and the object manager) for standard REXX.

The terms "class", "instance", "object", "property" and "method"
are used as usual. Objects are instances of a class. Objects have
properties that hold a value, and methods that can be called.
The term "module" is used for a special kind of objects that have
only a single implicit static instance. Modules also have properties
(variables) and methods (routines).

The following external REXX routines can be used to access the object
manager:
   iio_create     create an object
   iio_delete     delete an object
   iio_set        set the value of an object property or module property
   iio_get        get the value of an object property or module property
   iio_call       call an object method or module method



Object handles
--------------

Object handles are string values that are used to identify an
object. The format of the object handles is implementation
specific. The current implementation uses 8-character hexadecimal
numbers for object handles, but this could be changed in future
versions.

The special value "0" is used as a null object handle. "0" can
be used to reset properties that are object references.



Composite member names
----------------------

Property and method names are called member names.
The <iio_set>, <iio_get> and <iio_call> routines allow the
specification of composite member names. Composite member names
can contain the names of properties that are references of other
objects ("obj_prop_name" in the format description below). For
modules, composite member names also include the module name.

Composite member names for objects can have the following forms:
   member_name
   obj_prop_name.member_name
   obj_prop_name.obj_prop_name.member_name
   ...

Composite member names for modules can have the following forms:
   module_name.member_name
   module_name.obj_prop_name.member_name
   module_name.obj_prop_name.obj_prop_name.member_name
   ...



The <iio_create> routine
------------------------

<iio_create> is used to dynamically create new objects. It returns
an object handle that can be used as a reference to the object.

Syntax:
   obj_handle = iio_create(class_name)

Parameters:
   class_name  -  object class name
     <class_name> specifies the class name of the object to be
     created.

Return-Value:
   <iio_create> returns the object handle of the newly created object.

Example:
   terminal_h = iio_create("vt100_term")



The <iio_delete> routine
------------------------

<iio_delete> is used to delete an object that has been dynamically
created by the REXX program.

Syntax:
   call iio_delete obj_handle

Parameters:
   obj_handle  -  object handle
      <obj_handle> specifies the object handle of the object to be
      deleted. Once an object is deleted, it's object handle is
      no longer valid.

Example:
   call iio_delete terminal_h



The <iio_set> routine
---------------------

<iio_set> is used to set the value of an object property or module
property.

Syntax:
   call iio_set obj_handle, prop_name, prop_value

Parameters:
   obj_handle  -  object handle
      For objects properties, <obj_handle> specifies the object handle
      of the object whose property is to be set.
      For module properties, <obj_handle> must be empty.
   prop_name  -  property name
      <prop_name> is a composite member name that specifies the the
      property to be set.
   prop_value  -  property value
      <prop_value> specifies the new value for the property.

Examples:
   to set an object property:
      call iio_set terminal_h, "baud_rate", 9600
   to set a module property:
      call iio_set, "editor.lastfile", "readme.txt"



The <iio_get> routine
---------------------

<iio_get> is used to get the value of an object property or module
property.

Syntax:
   prop_value = iio_get(obj_handle,prop_name)

Parameters:
   obj_handle  -  object handle
      For object properties, <obj_handle> specifies the handle
      of the object whose property is to be returned.
      For module properties, <obj_handle> must be empty.
   prop_name  -  property name
      <prop_name> is a composite member name that specifies the
      property whose value is to be returned.

Return-Value:
   <prop_value> returns the value of the property.

Examples:
   For object properties:
      baud_rate = iio_get(terminal_h,"baud_rate")
   For module properties:
      last_file = iio_get(,"editor.last_file")



The <iio_call> routine
----------------------

<iio_call> is used to call object methods or module methods.
A method can be called as a procedure (no return-value) or as a
function (if it returns a value).
There are two variants to specify the method parameters, direct
syntax and symbolic syntax. The direct syntax version is simpler
than symbolic syntax version.

Syntax:
   direct syntax procedure:
      call iio_call obj_handle, method_name, parm1, parm2, parm3 ...
   direct syntax function:
      ret_val = iio_call(obj_handle,method_name,parm1,parm2,parm3...)
   symbolic syntax procedure:
      call iio_call obj_handle, "method_name p1 p2 p3 kw1=kp1 kw2=kp2 ..."
   symbolic syntax function:
      ret_val = iio_call(obj_handle,"method_name p1 p2 p3 kw1=kp1 ...")

Parameters:
   obj_handle  -  object handle
      For object methods, <obj_handle> specifies the handle of the
      object (or base object) to be used with the method call.
      For module methods, <obj_handle> must be empty.
   method_name  -  method name
      <method_name> is a composite member name that specifies the
      method to be called.

Parameters for the direct syntax:
   For the direct syntax, each method parameter is passed as a
   separate REXX parameter.
   For input parameters, the parameter value is passed.
   For output or update parameters, the name of a REXX variable
   (that contains the value) is passed.

Parameters for the symbolic syntax:
   For the symbolic syntax, the method name is followed by a list
   of positional parameters and keyword parameters.
   Positional parameters can be specified in the following forms:
      "... var_name ..."     name of a REXX variable
      "... 123 ..."          integer constant
      "... 'text' ..."       string constant
   Keyword parameters can be specified in the following forms ("kw"
   is the keyword name):
      "... kw=var_name ..."  name of a REXX variable
      "... kw=123 ..."       integer constant
      "... kw='text' ..."    string constant
      "... kw=",parm,"..."   value passed as a separate REXX parameter
   To pass an array, a REXX stem variable name can be specified.
   The <stem.0> element must contain the size of the array and
   the elements <stem.1>..<stem.n> contain the array elements.
   For string constants within the symbolic string, the standard
   REXX syntax is used. (Strings must be delimited by single or
   double-quote characters and delimiters within the string must
   be duplicated).

Return-value:
   <iio_call> returns the return-value of the method, if the method
   returns a value and if no result parameter is specified for the
   method. If the method does not return a value, the return-value
   of <iio_call> is undefined.

Examples:
   direct syntax procedure:
      for object methods:
         call iio_call terminal_h, "write", 10, 5, "please wait a moment"
      for module methods:
         call iio_call, "editor.shutdown", 1
   direct syntax function:
      for object methods:
         key = iio_call(terminal_h,"read",0)
      for module methods:
         i = iio_call(,"math.log",134)
   symbolic syntax procedure:
      for object methods:
         call iio_call terminal_h, "write line=10 column=5 text='pleas wait'"
         call iio_call terminal_h, "write line=l column=c text=s"
         call iio_call terminal_h, "write line=",10,"column=",5,"text=",s
         call iio_call terminal_h, "write 10 5 'please wait' color='red'"
      for module methods:
         call iio_call, "editor.shutdown prompt=1"
   symbolic syntax function:
      for object methods:
         key = iio_call(terminal_h,"read wait=0")
         key = iio_call(terminal_h,"read 0")
         key = iio_call(terminal_h,"read wait=",0)
         key = iio_call(terminal_h,"read wait=1 timeout=5")
      for module methods:
         i = iio_call(,"math.exp","a b")



Return-info values
------------------

Some methods use the special data type <ret_info> to return
completion information to the caller. <ret_info> information
can be stored in a normal REXX variable, or in a compound
variable.

If a normal REXX variable is used and if a <ret_info> event is
returned, the variable is set to a text message that describes
the <ret_info>. If no <ret_info> event is returned, the variable
is empty.

Example:
   call iio_call obj_h, "send s ri=ri"
   if ri <> "" then say "error:" ri

If a compound REXX variable is used, the elements of the compound
variable are set as follows:
   If no <ret_info> event has been returned:
      ri.0  =  0
      ri.1  =  undefined
      ri.2  =  undefined
   If a <ret_info> event has been returned:
      ri.0  =  2
      ri.1  =  list of unique <ret_info> event identifiers. This list
               contains the ID of the top-event, followed by the IDs
               of the super-events of the top-event. (The unique
               <ret_info> event identifiers are 16-bit hex numbers).
      ri.2  =  text message that describes the <ret_info>.

Example:
   call iio_call obj_h, "send s ri=ri."
   if ri.0 <> 0 then select
      when wordpos("0021",ri.1)<>0 then say "parity error"
      when wordpos("0022",ri.1)<>0 then say "overrun error"
      otherwise say "error:" ri.2
      end
