Contents Previous Next Subchapters

Writing An O-Matrix DLL Function in C++
See Also: linkdll , matrix

Description
This section describes how to write a C++ function that can be called from O-Matrix. The conventions for calling such a function are described in linkdll . This section specifies the link and what the parameters mean. Examples of O-Matrix callable C++ functions can be found in the sections mycolmax , myrowmax , bread

# include "dll.h"
This statement should appear at the beginning of the file that your C++ function is defined in. It defines the necessary types and macros for the C++ side of the link.

DLLPrototype(name)
This macro creates the prototype for a function that is called name in O-Matrix. It includes the linking convention for the function's parameters narg, nret, ret, arg, direct, allocate, free_mat, and error which are described below.

narg
This is an integer that specifies the number of arguments that are present in the O-Matrix call to name. In the syntax
     f(a, b, c, ... )
 the arguments are a, b, c, ... in that order. If this syntax is used, the corresponding value of nret is one.

nret
This is an integer that specifies the number of return values that are present in the O-Matrix call to name. In the syntax
     [A, B, C, ... ] = f(a, b, c, ... )
 the return values are A, B, C, ... in that order.

ret
This points to the matrix that contains the first return value for the function call. The matrix (ret + 1) contains the second return value and so on. See the matrix section for the meaning of each of the fields of a matrix. The first return value is initialized as follows:
     ret->nr    = 1
     ret->nc    = 1
     ret->br    = 1
     ret->nc    = 1
     ret->name  = EMPTY_STRING
     ret->type  = UNDEF_mat
 If you do not modify this matrix, the return value of name in O-Matrix will have type "novalue". The other return values are initialized in a similar fashion.

arg
This points to the matrix that is the first argument in the O-Matrix function call to name. The value (arg + i - 1) points to the i-th argument for i = 1, ... , narg.

direct
If a simple variable appears as an argument, such as a in the call
     f(a, b +  1, c.row(1))
 The corresponding value of arg->type is INDIRECT_mat or CONSTANT_mat. In this case the matrix points to another matrix that actually contains the information that the original matrix refers to. The function call
     direct(arg)
returns a pointer to the matrix that contains the information that the matrix pointer arg refers to. In the example function call above, if you modify the matrix pointed to by direct(arg) you will change the value of a in the calling routine. You must not do this if arg->type is CONSTANT_mat.

allocate
If you are returning a matrix that contains elements, you must allocate the memory for those elements using this routine because O-Matrix will free this memory when it is done with it. The function call
     allocate(mat)
sets the value of the field mat->adr to sufficient memory for all the elements in matrix pointed to by mat. This depends on the number of rows, mat->nr, the number of columns, mat->nc, and the type of the matrix, mat->type, when allocate is called. If the mat->adr field points to allocated memory, it should be freed using free_mat before a call to allocate. (Note that the call free_mat(mat) changes the value of mat->type.)

free_mat
The function call
     free_mat(mat)
frees the memory currently allocated for the elements in the matrix pointed to by mat. It also changes mat->type to be UNDEF_mat. If a matrix has type UNDEF_mat, INDIRECT_mat, or CONSTANT_mat, there is no memory allocated for its elements and this call is not necessary.

error
This function should be used to report errors that are detected while executing the function name. The function call
     error(help, message)
will post the O-Matrix execution error dialog with the specified message where help and message are '\0' terminated character vectors. Warning: this function call will not return and execution of your dll subroutine is immediately be aborted. Thus you should free any locally allocated memory before calling error. If the user chooses the Help button in the dialog, the file
     omwin\htm\help.htm
is displayed in the users default web browser (where help has been replaced by its value). These errors are like any other O-Matrix error and can be trapped .

prText
This function can be used to output text to the O-Matrix command window.
     prText("command", message)
will output the string message to the O-Matrix command window.