Re: Extensions documentation

[Paul Kienzle]

Pascal,

No, there is no good API definition.  All of the internals of Octave are
available to your function.  This is a mixed blessing.  On the one hand,
You can do absolutely anything, but on the other, modularity quickly gets
broken.  As far as I'm concerned Octave is not yet mature enough to have
a stable API.  At some point it would be worthwhile going through all the
DLD functions, seeing what they use, clean up the interface and only make
those bits visible.

Now, to answer your questions.

You let the octave interpreter know about your functions using 

DEFUN_DLD (name, args, nargout, "documentation string")
{
   octave_value_list retval;
   int nargin = args.length();

   // function body

   return retval;
}

The actual arguments are of type octave_value, and can be accessed
as args(0), args(1), ... args(nargin-1).  In practice, you will want
to manipulate the values as a specific type.  First you must test
that it is of the correct type, and then extract the value of that
type.  For example,

   if (args(0).is_real_scalar())  { 
      double v = args(0).double_value();

      // action to take when processing double argument
   }

The best source of information for useful operations on octave values
is in the file src/ov-base.h.

Usually you will be dealing with matrices in your octave file.  Liboctave
defines lots of operations on matrices, which are described (or at least
listed) in doc/liboctave.  You have the usual element-wise operators,
as well as matrix product, quotient, solvers, inverse, transpose, lu
decomposition, qr decomposition, etc.  The matrix types are Matrix,
RowVector, ColumnVector and DiagMatrix, plus Complex versions of this.
Most reasonable operations between these various types are defined.
There are also charMatrix and boolMatrix types with a different set
of operators.

All matrix elements can be accessed using subscripts as in x(i,j).
An element can either be assigned to or returned from.  You can force
bounds checking by using x.checkelem(i,j) as your element reference.
You can avoid bounds checking by using x.elem(i,j) as your element
reference.  Note that arrays in liboctave are copy-on-modify.  If you
assign one array to another, it simply copies a pointer to the data and
increments a reference count.  When you assign to an element of an array
which is referenced from two places, it makes a copy of the entire array.
x.xelem(i,j) does not check if it is a copy before operating.  If you are
passing the array to a FORTRAN or C subroutine, you can pass x.data()
if the function will not modify the array, or x.fortran_vec() if you
want to modify the array.  fortran_vec() will make a unique copy of the
array if it is referenced from more than one place.  Note that the data
is stored in FORTRAN rather than C array format.  In C, treat it as a
pointer to a vector, and reference the elements of the vector as rows*j+i.

The return values are easier since the octave_value constructor is
overloaded to automatically convert the basic types into octave values.
You simply assign retval(i) with the ith return value.  You don't need
to assign more than nargout values to retval since the interpreter will
simply throw away the rest.

In the Octave 2.1.x series, you can have multiple DEFUN_DLDs in the
same .oct file.  One of them must have the name of the oct file since
that's how the interpreter finds the correct file to load.  However,
once it is loaded, all DEFUN_DLD routines in the file are available.
The .oct file remains loaded until the DEFUN_DLD's are explicitly
cleared. [true?]  In practice, this means that you name the octave
file after your initialization procedure, and everything works fine.
I usually find that the interpreter crashes if I recompile the .oct file
out from under it, but I haven't tried it on recent versions of octave.

In Octave 2.0.x, each DEFUN_DLD needs to be in its own file of the same
name as the function.

I hope this helps.

Paul Kienzle
address@hidden

On Tue, Nov 07, 2000 at 04:57:20PM +0900, Pascal Fleury wrote:
> Hi!
> 
> I am using Octave to ease development, but I need to write some glue
> code to link it to the system I have.
> I tried to find some documentation about how to access parameters (input
> and output of functions), as well as
> some information of how many functions I can put into a single *.oct
> file, how they are "registered" to Octave
> or the way Octave finds them. I will also need to read HUGE amounts of
> data, but piece-wise. So am I sure that Octave
> will not unload my dyn-lib (.oct file), and let me loose the information
> I need to keep between calls, like a file descriptor for example ?
> 
> Does such a documentation exist ? Or shall I continue to dig in the
> examples, hoping to figure out the answers
> to my questions... Anyway, I think that beside academic work, we all
> have to link this to some existing systems routines. The interface is
> very well done, but lacks a little bit of description for more involved
> cases.
> 
> Thanks you for any help!
> Pascal
> 
> 

Content-Description: Card for Pascal Fleury



-------------------------------------------------------------
Octave is freely available under the terms of the GNU GPL.

Octave's home on the web:  http://www.octave.org
How to fund new projects:  http://www.octave.org/funding.html
Subscription information:  http://www.octave.org/archive.html
-------------------------------------------------------------