mkoctfile programming guide

[A. Danial]

I'm trying to create a dynamically loaded function with mkoctfile.
While the files in the src/DLD-FUNCTIONS have been a good starting
point they don't cover all the things I want to do (or they're
too difficult to understand).

Right now I'm stuck on how I can get a string which contains
the matrix name.  In matlab I'd use mxGetName().  I studied
Paul Kienzle's mex compatibility package for octave and tried to 
figure out the octave equivalent, but mex.cc has me utterly
baffled (not hard since I don't know C++).  Paul's mex package
works great on linux but I also need to run on AIX where dynamic
loading doesn't work.  For the the IBM systems I've resorted to 
rebuilding octave with my .cc code statically linked in so the
nifty mex package can't help me.

Since I've not been able to find a guide for writing programs with
mkoctfile (section 13.8 Dynamically Loaded Functions of the 2.1.34
release is a start) I figured I should put down everything I know in 
both octave and matlab dynamically loaded functions and post it.  
Hopefully, with contributions from others, it will evolve
into a guide, or maybe encourage a more knowledgeable person to put
a guide together.     -- Al


Some of the code segments below refer to a function which takes
two matrix arguments and returns three args:
    [a,b,c] = my_code(x,y)

Gateway function
----------------
octave: [code is in a file called my_code.cc]
        DEFUN_DLD(my_code, args, nargout, "help info") {
          octave_value_list retval;
          [user code; assign values to retval(0) (=x), retval(1) (=y)]
          return retval;
        }
matlab: [code is in a file called my_code.c]
        void mexFunction(int nlhs, mxArray *plhs[], int nrhs, 
                         const mxArray *prhs[]) {
          [user code; assign values to plhs[0] (=x), plhs[1] (=y)]
        }

Number of input arguments
-------------------------
octave:  args.length()
matlab:  nrhs

Number of output arguments
--------------------------
octave:  nargout
matlab:  nrls

Test: is ith input argument a scalar?
-------------------------------------
octave:  args(i).is_scalar_type()
matlab:  (mxGetN(prhs[i]) == 1) && (mxGetM(prhs[i]) == 1)

Test: is ith input argument a string?
-------------------------------------
octave:  args(i).is_string()
matlab:  mxIsChar(prhs[i])

Test: is ith input argument a matrix of doubles?
---------------------------------------------
octave:  args(i).is_matrix_type()
matlab:  mxIsDouble(prhs[i])

Test: is ith input argument a complex matrix?
---------------------------------------------
octave:  args(i).is_complex_matrix()
matlab:  mxIsComplex(prhs[i])

Allocate a 4 row by 5 column real matrix for the first output argument
----------------------------------------------------------------------
octave:  Matrix  out_args[2];  /* out_args[0] for x and out_args[1] for y */
         out_args[0] = Matrix(4, 5);
matlab:  plhs[0] = mxCreateDoubleMatrix(4, 5, mxREAL);

Allocate a 6 row by 7 column complex matrix for the second output argument
--------------------------------------------------------------------------
octave:  out_args[1] = ComplexMatrix(6, 7);  /* if out_args declared earlier */
matlab:  plhs[0] = mxCreateDoubleMatrix(6, 7, mxCOMPLEX);

Number of rows in the ith input argument
----------------------------------------
octave:  args(i).rows()
matlab:  mxGetM(prhs[i])

Number of columns in the ith input argument
-------------------------------------------
octave:  args(i).columns()
matlab:  mxGetN(prhs[i])

Fill the first output argument with data
----------------------------------------
octave:  for (int c=0; c < nCols; c++)
            for (int r=0; r < nRows; r++)
                out_args[0](r,c) = (double) r+c*nRows;
matlab:  double *M;
         M = mxGetPr(plhs[0]);
         for (int c=0; c < nCols; c++)
            for (int r=0; r < nRows; r++)
                M[r+c*nRows] = (double) r+c*nRows;

Fill the second output argument with complex data
-------------------------------------------------
octave:  for (int c=0; c < nCols; c++)
            for (int r=0; r < nRows; r++)
                out_args[1](r,c) = Complex( (double) r+c*nRows, (double) 0.0);
matlab:  double *Mr, *Mi;
         Mr = mxGetPr(plhs[1]);
         Mi = mxGetPi(plhs[1]);
         for (int c=0; c < nCols; c++)
            for (int r=0; r < nRows; r++) {
                Mr[r+c*nRows] = (double) r+c*nRows;
                Mi[r+c*nRows] = (double) 0.0;
            }

Populate the return value at the end of the gateway function
------------------------------------------------------------
octave:  for (int i = 0; i < nargout; i++) { retval(i) = out_args[i]; }
matlab:  <not applicable>

Generate an error message
-------------------------
octave:  error("there is a problem");
matlab:  mexErrMsgTxt("there is a problem");



-------------------------------------------------------------
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
-------------------------------------------------------------