Copyright: Hilfe PASMEX ® h#s 1997
Citation: ""


Index
MATLAB Externes Interface DLL - Hilfe für Programmierer

Die DLL "CMEX.DLL" beinhaltet die DLL-Variante der statischen Linkbibliotheken LIBMEXBC.LIB und LIBENGBC.LIB. Darin eingeschlossen ist die Bibliothek LIBMATBC.LIB. Diese neue DLL ermöglicht es, MATLAB-Routinen auch aus Borland Pascal bzw. Delphi zu nutzen. Aber auch für den C-Programmierer bedeutet der Einsatz dieser DLL eine deutliche Verringerung der Codegröße der eigenen Anwendungen sowie - bei massiver Verwendung - eine dramatische Einsparung von Hauptspeicherplatz.

Die Importbibliothek für Pascal definiert einige Strukturen etwas anders als im External Interface Guide beschrieben, um den besonderen Aspekten dieser Sprache gerecht zu werden.

Überblick DLL-Funktionen

eng-Funktionen: MATLAB als DDE-Server
mat-Funktionen: Zugriff auf .MAT-Dateien
mex-Funktionen: wenn eine DLL einen M-Skript ersetzt
mx-Funktionen: Portable Matrix-Zugriffe
sonstige Funktionen: spezielle Belange

Hinweise für Pascal-MEX-Programme

Was ist ein MEX-Programm?
Struktureller Aufbau
Beispiel

h#s © Technische Universität Chemnitz, Fachbereich Meß- und Sensortechnik


eng-Funktionen: MATLAB als DDE-Server

Folgende Funktionen stehen zur Verfügung:

engClose
engEvalString
engGetFull
engGetMatrix
engPutFull
engPutMatrix
engOpen
engOutputBuffer
engSetEvalCallback
engSetEvalTimeout
engWinInit


engClose

Deklaration:

function  engClose(ep: PEngine): Integer;

Beschreibung:

Schließt die MATLAB-Maschine.

Rückgabewert:

Die Funktion liefert 0 im Erfolgsfall.

Siehe auch:

engOpen


engEvalString

Deklaration:

function  engEvalString(ep: PEngine; str:PChar): Integer;

Beschreibung:

Führt ein über einen String spezifiziertes Kommando aus.

Rückgabewert:

Diese Funktion liefert 0 im Erfolgsfall.

Siehe auch:

mexEvalString, engOutputBuffer, engSetEvalCallback


engGetFull, engPutFull

Deklaration:

function  engGetFull(ep: PEngine; name:PChar; var m,n:LongInt; var pr,pi:HPDouble): Integer;
function  engPutFull(ep: PEngine; name:PChar; m,n:LongInt; pr,pi:HPDouble): Integer;

Beschreibung:

Einfacher Weg, "volle" Matrizen ins MATLAB zu schreiben bzw. daraus zu lesen.

Parameter:

ep	MATLAB-Maschinen-Zeiger;

name	Name der Matrix;

m	Anzahl der Matrix-Zeilen;

n	Anzahl der Matrix-Spalten;

pr	Huge-Zeiger auf Realteil-Feld;

pi	Huge-Zeiger auf Imaginärteil-Feld.

engGetFull alloziert Speicher für das Real- und Imaginärteil-Feld mit mxCalloc; es ist mxFree zu verwenden, um das Feld freizugeben.

Sollte die Matrix angegebenen Namens noch nicht existieren, kreiert engPutFull eine neue Matrix; andernfalls wird die vorhandene überschrieben.

Rückgabewert:

Diese Funktionen liefern 0 im Erfolgsfall, sowie 1, falls der Variablenname nicht aufgefunden werden konnte.

Siehe auch:

engOpen, mexGetFull; TMatrix


engGetMatrix, matPutMatrix
engGetMatrix, engPutMatrix

Deklaration:

function  engGetMatrix(ep: PEngine; name:PChar): PMatrix;
function  engPutMatrix(ep: PEngine; pm:PMatrix): Integer;

Beschreibung:

Liest eine Matrix ein bzw. schreibt eine Matrix in die MATLAB-Maschine. Die Matrizen werden kopiert, daher muß die Matrix nach dem Kopieren auch wieder freigegeben werden.

Sollte die Matrix angegebenen Namens noch nicht existieren, kreiert engPutMatrix eine neue Matrix; andernfalls wird die vorhandene überschrieben.

Rückgabewert:

engGetMatrix liefert einen Zeiger auf die Matrix angegebenen Namens. Existiert diese nicht, liefert diese Funktion nil.

engPutMatrix liefert 0 im Erfolgsfall.

Siehe auch:

engOpen, mexGetMatrix, engGetFull, mxFreeMatrix; TMatrix


engOpen

Deklaration:

function  engOpen(startcmd:PChar): PEngine;

Beschreibung:

Öffnet eine MATLAB-Maschine.

Parameter:

startcmd	Kommandozeile (<pfad\>MATLAB.EXE <parameter>).

Rückgabewert:

Diese Funktion liefert einen Zeiger auf eine Engine-Struktur im Erfolgsfall, sonst nil.

Siehe auch:

engWinInit, engClose; TEngine


engOutputBuffer

Deklaration:

procedure engOutputBuffer(ep: PEngine; p:PChar; n:Integer);

Beschreibung:

Definiert den Ausgabe-Puffer für die Funktion engEvalString, deren Standardausgabe in diesen hinein umgelenkt wird.

Parameter:

ep	Zeiger auf MATLAB-Maschinen-Struktur;

p	Zeiger auf Zeichen-Puffer;

n	Länge des Puffers.

Siehe auch:

engOpen, engEvalString; TEngine


engSetEvalCallback

Deklaration:

procedure engSetEvalCallback(ep: PEngine; callback:TFarProc);

Beschreibung:

Ermöglicht "non-blocking" engEvalString-Aufrufe, d.h. engEvalString kehrt sofort zurück, und nach Ausführung des Kommandos wird der Callback gerufen. Per Vorgabe ist "blocking call" gesetzt, d.h. der Aufrufer ist blockiert, solange MATLAB das Kommando bearbeitet.

Parameter:

ep	Zeiger auf MATLAB-Maschinen-Struktur;

callback	Zeiger auf eine Prozedur ohne Parameter. Diese wird bei Beendigung der Kommandoausführung von mexEvalString gerufen. Die Rückruffunktion muß mit export; versehen werden.

Siehe auch:

engOpen, engEvalString; TEngine


engSetEvalTimeOut

Deklaration:

procedure engSetEvalTimeout(ep: PEngine; timeout:LongInt);

Beschreibung:

Setzt ein Zeitlimit für die Routinen engEvalString, engGetXXX und engPutXXX. Die Vorgabe ist 3000 ms.

Parameter:

ep	Zeiger auf MATLAB-Maschinen-Struktur;

timeout	Zeitlimit in Millisekunden.

Siehe auch:

engEvalString, engGetMatrix; TEngine


engWinInit

Deklaration:

procedure engWinInit(hInstance:THandle);

Beschreibung:

Initialisiert die DLL mit dem Instanz-Handle der kommanikationswilligen Applikation. Dieser Aufruf muß allen anderen engXXX-Aufrufen vorausgehen.

Parameter:

hInstance	Instanz-Handle.

Siehe auch:

engOpen


mat-Funktionen: Zugriff auf .MAT-Dateien

Folgende Funktionen stehen zur Verfügung:

matClose
matDeleteMatrix
matGetDir
matGetFp
matGetFull
matGetMatrix
matGetNextMatrix
matGetString
matOpen
matPutFull
matPutMatrix
matPutString


matClose

Deklaration:

function  matClose(ph:PMatFile): Integer;

Beschreibung:

Schließt eine MAT-Datei.

Rückgabewert:

Die Funktion liefert 0 im Erfolgsfall.

Siehe auch:

matOpen; _lclose


matDeleteMatrix

Deklaration:

function  matDeleteMatrix(ph:PMatFile; name:PChar): Integer;

Beschreibung:

Löscht eine Matrix angegbenen Namens aus der geöffneten Datei.

Rückgabewert:

Im "External Interface Guide" liefert diese Funktion void, was in Anbetracht der Logik, der .LIB und der Header-Dateien unlogisch erscheint. Sehr wahrscheinlich liefert die Funktion 0 im Erfolgsfall, ansonsten einen Fehlercode.

Siehe auch:

matOpen


matGetDir

Deklaration:

function  matGetDir(ph:PMatFile; var num:LongInt): PPChar;

Beschreibung:

Listet die Namen der enthaltenen Matrizen auf. Der Ergebniszeiger zeigt auf ein nil-terminiertes Feld von Stringzeigern, die ihrerseits wiederum auf nullterminierte Strings (die Variablennamen) zeigen. (Eine MAT-Datei ist nicht hierarchisch aufgebaut, sondern flach.) Gleichzeitig ist der Rückgabewert ein Zeiger auf einen mit mxCalloc allozierten Speicherbereich, der mit mxFree freigegeben werden muß.

Rückgabewert:

Die Funktion liefert den angegeben Zeiger im Erfolgsfall, andernfalls nil.

Die Variable m enthält nach Aufruf die Größe des mit mxCalloc allozierten Speicherbereiches.

Siehe auch:

matOpen, mxFree; qsort


matGetFp

Deklaration:

function  matGetFp(ph:PMatFile): PFile;

Beschreibung:

Liefert einen Zeiger auf die Borland-C-3.1-FILE-Struktur (Speichermodell "large"), die mit ph verbunden ist. Hiermit könnten unter C Bibliotheksfunktionen wie ferror() oder feof() ausgeführt werden. Unter Pascal mag das Dateihandle von Interesse sein.

Siehe auch:

matOpen; TFile; ferror, feof


matGetFull, matPutFull

Deklaration:

function  matGetFull(ph:PMatFile; name:PChar; var m,n:LongInt; var pr,pi:HPDouble): Integer;
function  matPutFull(ph:PMatFile; name:PChar; m,n:LongInt; pr,pi:HPDouble): Integer;

Beschreibung:

Einfachster Weg, "volle" Matrizen in MAT-Dateien zu schreiben bzw. davon zu lesen.

Parameter:

ph	Geöffnete MAT-Datei;

name	Name der Matrix;

m	Anzahl der Matrix-Zeilen;

n	Anzahl der Matrix-Spalten;

pr	Huge-Zeiger auf Realteil-Feld;

pi	Huge-Zeiger auf Imaginärteil-Feld.

matGetFull alloziert Speicher für das Real- und Imaginärteil-Feld mit mxCalloc; es ist mxFree zu verwenden, um das Feld freizugeben.

Sollte die Matrix angegebenen Namens noch nicht existieren, kreiert matPutFull eine neue Matrix; andernfalls wird die vorhandene überschrieben.

Rückgabewert:

Diese Funktion liefert 0 im Erfolgsfall, sowie 1, falls der Variablenname nicht aufgefunden werden konnte.

Siehe auch:

matOpen, mexGetFull; TMatrix


matGetMatrix, matPutMatrix

Deklaration:

function  matGetMatrix(ph:PMatFile; name:PChar): PMatrix;
function  matPutMatrix(ph:PMatFile; pm:PMatrix): Integer;

Beschreibung:

Liest eine Matrix ein bzw. schreibt eine Matrix in die geöffnete MAT-Datei. Die Matrizen werden kopiert, daher muß die Matrix nach dem Kopieren auch wieder freigegeben werden.

Sollte die Matrix angegebenen Namens noch nicht existieren, kreiert matPutMatrix eine neue Matrix; andernfalls wird die vorhandene überschrieben.

Rückgabewert:

matGetMatrix liefert einen Zeiger auf die Matrix angegebenen Namens. Existiert diese nicht, liefert diese Funktion nil.

matPutMatrix liefert 0 im Erfolgsfall.

Siehe auch:

matOpen, mexGetMatrix, matGetFull, mxFreeMatrix; TMatrix


matGetNextMatrix

Deklaration:

function  matGetNextMatrix(ph:PMatFile): PMatrix;

Beschreibung:

Liest die nächste Matrix nach matOpen oder matGetNextMatrix ein. Die Matrizen werden kopiert, daher muß die Matrix nach dem Kopieren auch wieder freigegeben werden.

Diese Funktion darf nicht in Verbindung mit anderen mat-Funktionen genutzt werden; ansonsten ist das Verhalten undefiniert.

Rückgabewert:

Die Funktion liefert einen Zeiger auf die Matrix angegebenen Namens. Wurde das Dateiende erreicht, oder bei einem anderen Fehler liefert diese Funktion nil.

Siehe auch:

matOpen, mxFreeMatrix; TMatrix


matGetString, matPutStringl
matGetString, matPutString

Deklaration:

function  matGetString(ph:PMatFile; name:PChar; str:HPChar; strlen:LongInt): Integer;
function  matPutString(ph:PMatFile; name:PChar; str:HPChar): Integer;

Beschreibung:

Einfachster Weg, Zeichenketten-Matrizen in MAT-Dateien zu schreiben bzw. davon zu lesen.

Parameter:

ph	Geöffnete MAT-Datei;

name	Name der Matrix;

str	Zeiger auf Zeichenkette (auch >64K möglich);

strlen	Größe des bereitgestellten Speichers.

Rückgabewert:

Diese Funktion liefert 0 im Erfolgsfall. Fehlercodes von matGetString sind:

1	Matrix ist keine String-Matrix;

2	Länge des Strings ist größer als str_len;

3	Datei-Lesefehler.

Siehe auch:

matOpen, mexGetFull; TMatrix


matOpen

Deklaration:

function  matOpen(filename,mode:PChar): PMatFile;

Beschreibung:

Öffnet eine MAT-Datei.

Parameter:

filename	Dateiname der zu öffnenden MAT-Datei;

mode	Öffnungs-Modus im C-Stil (als String):

 'r'	Öffnen der Datei im Nur-Lese-Modus;

 'u'	Öffnen der Datei zum Lesen und Schreiben;

 'w'	Kreieren der Datei unter Löschung einer bereits vorhandenen.

Rückgabewert:

Diese Funktion liefert 0 im Erfolgsfall. Fehlercodes von matGetString sind:

1	Matrix ist keine String-Matrix;

2	Länge des Strings ist größer als str_len;

3	Datei-Lesefehler.

Siehe auch:

matOpen, mexGetFull; TMatrix


mex-Funktionen: wenn eine DLL einen M-Skript ersetzt

Folgende Funktionen stehen zur Verfügung:

mexAtExit
mexCallMATLAB
mexErrMsgTxt
mexEvalString
mexFunction
mexGetFull
mexGetGlobal
mexGetMatrix
mexGetMatrixPtr
mexPrintf
mexPutFull
mexPutMatrix
mexSetTrapFlag


mexAtExit

Deklaration:

function  mexAtExit(ExitFcn:TFarProc): Integer;

Beschreibung:

Registriert eine Funktion, die beim Shutdown (clear mex) aufgerufen wird. Die Prozedur selbst muß FAR-kodiert sein und wird ohne Übergabeparameter gerufen.

Rückgabewert:

Diese inline-Funktion liefert immer Null.

Siehe auch:

WEP


mexCallMATLAB

Deklaration:

function  mexCallMATLAB(nlhs:Integer; var plhs:TMatArr; nrhs:Integer; const prhs:TMatArr; name:PChar): Integer;

Beschreibung:

Ruft eine MATLAB-interne Funktion oder andere externe Funktionen über ihren Namen. Die Parameter entsprechen denen von mexFunction. MATLAB-Operatoren wie Matrizen-Multiplikation und -division werden als Operatoren-Strings wie '*' und '/' spezifiziert.

Diese Funktion kann neue Matrix-Strukturen (als Ergebnis) erzeugen; es ist wichtig, daß diese Strukturen auch wieder freigegeben werden.

Rückgabewert:

Normalerweise kehrt diese Funktion im Fehlerfall niemals zurück. Wurde jedoch mittels mexSetTrapFlag ein anderes Fehlerverhalten festgelegt; in diesem Fall kehrt die Funktion im Erfolgsfall mit 0 zurück.

Siehe auch:

mexFunction, mexSetTrapFlag, mexEvalString


mexErrMsgTxt

Deklaration:

procedure mexErrMsgTxt(error_msg:PChar);

Beschreibung:

Schreibt eine Fehlermeldung in das MATLAB-Kommandofenster und bricht die Ausführung ab. Mit mxCalloc allozierter Speicher wird freigegeben.

Rückgabewert:

Diese Funktion kehrt niemals zurück.

Siehe auch:

mexPrintf


mexEvalString

Deklaration:

function  mexEvalString(str:PChar):Integer;

Beschreibung:

Führt ein über einen String spezifiziertes Kommando aus.

Rückgabewert:

Diese Funktion liefert 0 im Erfolgsfall.

Siehe auch:

mexCallMATLAB


mexFunction

Deklaration:

procedure mexFunction(nlhs:Integer; var plhs:TMatArr; nrhs:Integer; const prhs:TMatArr); export;

Beschreibung:

Eintrittspunkt in ein "MATLAB-Executable" (MEX oder DLL-MEX). Diese Funktion wird von MATLAB gerufen. Der Versuch, die gleichnamige Funktion in CMEX.DLL zu rufen führt zu einem "abstrakt"-Fehler. (Insofern ist CMEX.DLL nichts anderes als eine gewöhnliche MEX-Datei.)

Parameter:

nlhs	Anzahl der (linksseitigen - left-hand) Ergebniswerte;

plhs	Matrizen-Feld der (linksseitigen) Ergebniswerte, null-basiert;

nrhs	Anzahl der (rechtsseitigen - right-hand) Funktionsargumente;

prhs	Matrizen-Feld der (rechtsseitigen) Funktionsargumente, null-basiert.

Ist nlhs=0, ist plhs dennoch ein Array mit einem Element; plhs[0]^ ist kein ungültiger Zugriff, liefert jedoch zunächst einen nil-Zeiger. Wird dieses Element mit einer Rückgabematrix belegt, wird diese der Variable "ans" zugewiesen.

Siehe auch:

mexCallMATLAB


mexGetFull, mexPutFull

Deklaration:

function  mexGetFull(name:PChar; var m,n:LongInt; var pr,pi:HPDouble): Integer;
function  mexPutFull(name:PChar; m,n:LongInt; pr,pi:HPDouble): Integer;

Beschreibung:

Einfacherer Weg, "volle" Matrizen in den globalen Arbeitsspeicher zu setzen bzw. von da zu holen.

Parameter:

name	Name der Matrix;

m	Anzahl der Matrix-Zeilen;

n	Anzahl der Matrix-Spalten;

pr	Huge-Zeiger auf Realteil-Feld;

pi	Huge-Zeiger auf Imaginärteil-Feld.

mexGetFull alloziert Speicher für das Real- und Imaginärteil-Feld mit mxCalloc; es ist mxFree zu verwenden, um das Feld freizugeben.

Sollte die Matrix angegebenen Namens noch nicht existieren, kreiert mexPutFull eine neue Matrix; andernfalls wird die vorhandene überschrieben.

Rückgabewert:

Diese Funktion liefert 0 im Erfolgsfall.

Siehe auch:

mexGetMatrix


mexGetMatrix, mexPutMatrix

Deklaration:

function  mexGetMatrix(name:PChar): PMatrix;
function  mexPutMatrix(pm:PMatrix): Integer;

Beschreibung:

Holt bzw. setzt Matrizen in den globalen Arbeitsspeicher. Die Matrizen werden kopiert, daher muß die Matrix nach dem Kopieren auch wieder freigegeben werden.

Sollte die Matrix angegebenen Namens noch nicht existieren, kreiert mexPutMatrix eine neue Matrix; andernfalls wird die vorhandene überschrieben.

Rückgabewert:

mexGetMatrix liefert einen Zeiger auf die Matrix angegebenen Namens. Existiert diese nicht, liefert diese Funktion nil.

mexPutMatrix liefert 0 im Erfolgsfall.

Siehe auch:

mexGetMatrixPtr, mexGetFull, mxFreeMatrix; TMatrix


mexGetGlobal, mexGetMatrixPtr

Deklaration:

function  mexGetGlobal(name:PChar): PMatrix;
function  mexGetMatrixPtr(name: PChar): PMatrix;

Beschreibung:

Holt Matrizen vom globalen Arbeitsspeicher. Die Matrizen durch Zeiger referenziert; der Inhalt wird nicht kopiert, daher darf die Matrix nicht freigegeben werden.

Aus der Matrix können Werte gelesen sowie geändert werden, vorausgesetzt, die Größe und der Typ der Matrix (rell/komplex, "voll"/"dünn", numerisch/String) bleibt bestehen.

Anscheinend ist mexGetGlobal ein vergessenes Alias aus alten Tagen.

Rückgabewert:

mxGetMatrixPtr liefert einen Zeiger auf die Matrix angegebenen Namens. Existiert diese nicht, liefert diese Funktion nil.

Siehe auch:

mexGetMatrix, mexGetFull; TMatrix


mexPrintf, mexVPrintf

Deklaration:

procedure mexPrintf(format:PChar); cdecl; {in Delphi}
procedure mexVPrintf(format:PChar; const Args; arglen:Word);

Beschreibung:

Gibt wie die C-Funktionen printf() und vprintf() Zeichen auf die Standardausgabe (hier: das MATLAB-Kommandofenster). Da mexVPrintf unglücklicherweise auf mexPrintf aufsetzen muß, ist die Angabe der Argument-Länge vonnöten, um den Stack-Kopiervorgang durchführen zu können.

Achtung: mexPrintf darf nicht ohne besondere Vorkehrungen von Borland Pascal benutzt werden; der Aufrufer muß die umgekehrte Push-Reihenfolge beachten und den Stack selbst aufräumen! Unter Delphi wird dies durch die Anweisung cdecl unterstützt; allerdings unterstützt Delphi die variable Parameterliste nicht.

mexVPrintf hat diese Einschränkungen nicht.

Rückgabewert:

Im Gegensatz zu ihren C-Pedanten, die die Anzahl der geschriebenen Zeichen zurückliefern, liefern diese Implementierungen kein Ergebnis.

Siehe auch:

mexErrMsgTxt; cdecl, printf; TMatrix


mexSetTrapFlag

Deklaration:

procedure mexSetTrapFlag(trap_flag:Bool);

Beschreibung:

Setzt das Verhalten von mexCallMATLAB im Fehlerfall. Da diese Funktion in ihrem Gültigkeitsbereich global ist, bedeutet ihre Verwendung auch die Beeinflussung anderer DLL-MEX-Funktionen, die die CMEX.DLL verwenden.

Parameter:

Ist trap_flag=TRUE, liefert mexCallMATLAB im Fehlerfall einen Wert ungleich 0 zurück. Ist dagegen trap_flag=FALSE, kehrt mexCallMATLAB im Fehlerfall nicht zurück

Siehe auch:

mexCallMATLAB


mx-Funktionen: Portable Matrix-Zugriffe

Diese Funktionen dienen dem portablen Zugriff auf die MATLAB-Matrix-Struktur.

mxCalloc
mxCreateFull
mxCreateSparse
mxCreateString
mxFree
mxFreeMatrix
mxGetName
mxGetIr
mxGetJc
mxGetLibVersion
mxGetM
mxGetN
mxGetNzmax
mxGetPi
mxGetPr
mxGetScalar
mxGetString
mxIsComplex
mxIsDouble
mxIsFull
mxIsNumeric
mxIsSparse
mxIsString
mxSetIr
mxSetJc
mxSetM
mxSetN
mxSetName
mxSetNzmax
mxSetPi
mxSetPr


mxCalloc, mxFree

Deklaration:

function  mxCalloc(n,size:Word): HPChar;
procedure mxFree(p:HPChar);

Beschreibung:

Grundlegende Funktionen zur Anforderung und Freigabe von Speicher. Ihre Benutzung stellt die Freigabe bei abnormalem Abbruch sicher.

mxCalloc belegt Speicher in der Größe n*size Bytes und setzt den Inhalt zu Null. Bei Rückkehr von einer MEX-Funktion wird dieser automatisch freigegeben.

Rückgabewert:

mxCalloc gibt einen Huge-Zeiger auf den angeforderten Speicherbereich zurück

Siehe auch:

New, Dispose


mxCreateFull, mxCreateSparse, mxFreeMatrix

Deklaration:

function  mxCreateFull(m,n:LongInt; ComplexFlag:LongBool): PMatrix;
function  mxCreateSparse(m,n,nzmax:LongInt; ComplexFlag:LongBool): PMatrix;
procedure mxFreeMatrix(pm:PMatrix);

Beschreibung:

Funktionen zum Anlegen und Freigeben ganzer Matrizen ("voll" oder "dünn"). mxFreeMatrix gibt auch den Speicher aller anhängigen Arrays frei.

Parameter:

m	Anzahl der Matrix-Zeilen;

n	Anzahl der Matrix-Spalten;

nzmax	Maximalzahl der Einträge ungleich Null in einer "dünnen" Matrix;

ComplexFlag	Boolean-Angabe, ob die zu erzeugende Matrix Imaginärteile haben (TRUE) oder rein rell sein soll (FALSE);

pm	Zeiger auf Matrix.

mxCreateXXX alloziert Speicher für das Real- und ggf. Imaginärteil-Feld mit mxCalloc.

Rückgabewert:

mxCreateXXX geben einen Zeiger auf die allozierte Matrix-Struktur mitsamt gültigen Zeigern für die Zeiger innerhalb der Struktur zurück.

Siehe auch:

mxCreateString; TMatrix


mxCreateString, mxGetString

Deklaration:

function  mxCreateString(str:HPChar):PMatrix;
function  mxGetString(pm:PMatrix; str:HPChar; strlen:LongInt): Integer;

Beschreibung:

Funktionen zum Anlegen einer String-Matrix sowie zum Abfragen des Strings in der Matrix. Die Angabe str_len bezieht sich auf die Größe des Pufferspeichers von str_ptr. Die Allozierung eines geeigneten Puffers kann durch Auswerten der Matrix-Dimensionen erfolgen. Hat die Matrix mehrere Dimensionen, werden die Zeichen spaltenweise(!) aneinandergereiht.

Parameter:

pm	Zeiger auf Matrix;

str	Zeiger auf nullterminierten String bzw. Pufferspeicher;

strlen	Puffergröße, mithin Maximalgröße des auszulesenden String+1.

mxCreateString alloziert Speicher für das Real-Feld mit mxCalloc. Die Zeichenablage erfolgt spaltenweise in einer Matrix mit einer Zeile (mxGetM würde 1 liefern).

Rückgabewert:

mxCreateString gibt einen Zeiger auf die allozierte Matrix-Struktur mitsamt gültigem Zeiger für die Realteile innerhalb der Struktur zurück.

mxGetString liefert 0 im Erfolgsfall.

Siehe auch:

mxCreateFull, mxIsString; TMatrix


mxGetIr, mxGetJc, mxSetIr, mxSetJc

Deklaration:

function  mxGetIr(pm:PMatrix): HPLongInt;
function  mxGetJc(pm:PMatrix): HPLongInt;
procedure mxSetIr(pm:PMatrix; ir:HPLongInt);
procedure mxSetJc(pm:PMatrix; jc:HPLongInt);

Beschreibung:

Funktionen zum Zugriff auf die ir- und jc-Elemente einer Matrix.

Rückgabewert:

Ist die Matrix "voll" (nicht "dünn"), liefern mxGetIr und mxGetJc nil. Ansonsten handelt es sich dabei um Huge-Zeiger auf Longint-Arrays.

Siehe auch:

mxCreateFull, mxIsSparse; TMatrix


mxGetM, mxGetN, mxSetM, mxSetN

Deklaration:

function  mxGetM(pm:PMatrix): LongInt;
function  mxGetN(pm:PMatrix): LongInt;
procedure mxSetM(pm:PMatrix; m:LongInt);
procedure mxSetN(pm:PMatrix; n:LongInt);

Beschreibung:

Funktionen zum Zugriff auf die Anzahl von Zeilen und Spalten einer Matrix.

Rückgabewert:

mxGetX liefern die Anzahl der Zeilen (M) bzw. Spalten (N).

Siehe auch:

mxCreateFull, mxGetScalar; TMatrix


mxGetName, mxSetName

Deklaration:

function  mxGetName(pm:PMatrix): PChar;
procedure mxSetName(pm:PMatrix; name:PChar);

Beschreibung:

Funktionen zum Zugriff auf den Namen einer Matrix. Die Maximallänge des Namens ist durch die Konstante mxMAXNAM (=20, inklusive Abschluß-Null gerechnet) gegeben.

Rückgabewert:

Der Rückgabewert bei mxGetName zeigt in die Matrix-Struktur und ist insofern "langlebig".

Siehe auch:

mxCreateFull; TMatrix


mxGetNzmax, mxSetNzmax

Deklaration:

function  mxGetNzmax(pm:PMatrix): LongInt;
procedure mxSetNzmax(pm:PMatrix; nzmax:LongInt);

Beschreibung:

Funktionen zum Zugriff auf die maximale Anzahl von Einträgen ungleich Null in einer "dünnen" Matrix. Handelt es sich bei pm um eine volle Matrix, ist das Funktionsergebnis nicht definiert. Diese Funktion verändert nicht die Länge des ir-Feldes - dies muß der Anwender konsistent halten!

Rückgabewert:

s.o.

Siehe auch:

mxCreateSparse; TMatrix


mxGetPi, mxGetPr, mxSetPi, mxSetPr

Deklaration:

function  mxGetPi(pm:PMatrix): HPDouble;
function  mxGetPr(pm:PMatrix): HPDouble;
procedure mxSetPi(pm:PMatrix; pi:HPDouble);
procedure mxSetPr(pm:PMatrix; pr:HPDouble);

Beschreibung:

Funktionen zum Zugriff auf die Zeiger auf Real- (Pr) und Imaginärteile (Pi) von Matrixelementen. Die zugehörigen Speicherbereiche werden mit mxCalloc belegt und mit mxFree freigegeben - daher muß der Anwender diese Felder ebenfalls mit diesem Funktionspaar allozieren bzw. freigeben.

Rückgabewert:

mxGetXX liefern Zeiger auf ein Huge-Feld von Double-Werten. Sind mehr als 8K Doubles zu erwarten, muß mit Huge-Zeigern gearbeitet werden.

mxGetPi liefert nil, wenn die Matrix rein reell ist.

Siehe auch:

IncHP, mxIsComplex, mxCalloc; TMatrix


mxGetScalar

Deklaration:

function  mxGetScalar(pm:PMatrix): Double;

Beschreibung:

Diese Funktion bietet einen einfachen Zugriff auf das (1,1)-Element der Matrix pm.

Rückgabewert:

Gemäß üblicher Pascal-Konvention liegt das Ergebnis auf der Spitze des Koprozessor-Stacks

Siehe auch:

mxIsComplex, mxIsNumeric, mxGetM; TMatrix


mxIsComplex

Deklaration:

function  mxIsComplex(pm:PMatrix): Bool;

Beschreibung:

Diese Funktion testet, ob die Matrix pm Imaginärteile besitzt, d.h. der Zeiger pi der Matrix-Struktur nicht nil ist.

Rückgabewert:

das Testergebnis

Siehe auch:

mxGetPi, mxIsNumeric; TMatrix


mxIsDouble

Deklaration:

function  mxIsDouble(pm:PMatrix): Bool;

Beschreibung:

Diese Funktion testet, ob die Matrix aus Double-Werten besteht.

Rückgabewert:

Diese Funktion liefert mit dieser MATLAB-Version immer TRUE.

Siehe auch:

TMatrix


mxIsFull, mxIsSparse

Deklaration:

function  mxIsFull(pm:PMatrix): Bool;
function  mxIsSparse(pm:PMatrix): Bool;

Beschreibung:

Diese beiden zueinander komplementären Funktionen testen, ob die Matrix pm "voll" oder "dünn" ist.

Rückgabewert:

mxIsFull liefert TRUE, wenn die Matrix "voll" ist, sonst FALSE

mxIsSparse liefert TRUE, wenn die Matrix "dünn" ist, sonst FALSE

Siehe auch:

TMatrix


mxIsNumeric, mxIsString

Deklaration:

function  mxIsNumeric(pm:PMatrix): Bool;
function  mxIsString(pm:PMatrix): Bool;

Beschreibung:

Diese beiden zueinander komplementären Funktionen testen, ob die Matrix pm numerisch ist oder aus Zeichen besteht.

Rückgabewert:

mxIsNumeric liefert TRUE, wenn die Matrix numerisch ist, sonst FALSE

mxIsString liefert TRUE, wenn die Matrix aus Zeichen besteht, sonst FALSE

Siehe auch:

TMatrix


sonstige Funktionen: spezielle Belange von Pascal und der DLL

Für diese Funktionen gibt es keine Entsprechungen in den statischen Linkbibliotheken (.LIB). Zum einen dienen sie zum Zugriff auf dort enthaltene Variablen, zum anderen werden Funktionen für die Arbeit mit Huge-Zeigern angeboten, was in Pascal normalerweise unüblich ist. mexVPrintf ermöglicht die Ausgabe ins MATLAB-Fenster unter Angabe einer beliebigen Werteliste. Schließlich rundet mxGetLibVersion die DLL ab, um die zugrundeliegende Version der statischen Linkbibliotheken in Erfahrung bringen zu können.

DecHP
hInstDLL
hInstMATLAB
hWndMATLABCmd
IncHP
IncHPL
mexVPrintf
mxGetLibVersion
wDataSegment
wHeapSize


hInstDLL, hInstMATLAB, hWndMATLABCmd, wDataSegment, wHeapSize

Deklaration:

function  hInstDLL: THandle;
function  hInstMATLAB: THandle;
function  hWndMATLABCmd: HWnd;
function  wDataSegment: Word;
function  wHeapSize: Word;

Beschreibung:

Funktionen zum Zugriff auf Variablen innerhalb der ehemals statischen Linkbibliotheken.

Rückgabewert:

hInstDLL:	Instanz-Handle der CMEX.DLL;

hInstMATLAB:	Instanz-Handle der laufenden MATLAB-Applikation;

hWndMATLABCmd:	Fenster-Handle des MATLAB-Kommandofensters;

wDataSegment:	Datensegment-Selektor der CMEX.DLL;

wHeapSize:	Größe des lokalen Heaps der CMEX.DLL.

Siehe auch:

Windows-Funktionen LoadLibrary, CreateWindow


DecHP, IncHP, IncHPL

Deklaration:

procedure DecHP(var P:Pointer; by:Word);
procedure IncHP(var P:Pointer; by:Word);
procedure IncHPL(var P:Pointer; by:LongInt);

Beschreibung:

Funktionen zum korrekten "Vorrücken" von Huge-Zeigern unter Borland Pascal und Delphi. Da dem Parameter P die Größeninformation unbekannt ist, bezieht sich der Parameter by auf Bytes. Ein Huge-Zeiger auf Double-Werte ist dabei wie folgt um 1 Element vorzurücken:

IncHP(Pointer(DoubleZeiger),sizeof(Double));

IncHPL ermöglicht in Verbindung mit dem Vorzeichen von by sowohl Inkrementieren als auch Dekrementieren des Zeigers P, auch um genau 64K und mehr.

Mit diesen Funktionen sollte das 64K-Limit von Pascal-Arrays endgültig fallengelassen werden. Das ganze funktioniert sogar im Real- und Standardmodus von Windows.

Siehe auch:

Windows-Funktionen _hread, _hwrite, hmemcpy


mxGetLibVersion

Deklaration:

function  mxGetLibVersion:Word;

Beschreibung:

Diese Funktion liefert die Versionsnummer von MATLAB, zu der die in die DLL eingesetzten Bibliotheken gehören.

Rückgabewert:

Das High-Byte enthält die Hauptversionsnummer, das Low-Byte die Nebenversionsnummer in Hundertstel. Die vorliegende CMEX.DLL liefert 4*256+20, als Kennung für MATLAB 4.2.

Siehe auch:

sonstige Funktionen


Was ist ein MEX-Programm?

MATLAB als ein skriptbasiertes Programm erlaubt das Starten von Binärcode anstelle der Ausführung eines .M-Skriptes bei einem Funktionsaufruf. Voraussetzung hierfür ist, daß sich eine DLL gleichen Namens und mit festgelegtem Aufbau im Kommandosuchpfad befindet. Eine solche DLL wird auch als MEX- (MATLAB-Executable) Datei bezeichnet. Eine DLL verkörpert somit genau einen Funktionsnamen. Mit Hilfe solcher Unterprogramme lassen sich folgende Spezialfälle der MATLAB-Programmierung lösen:

-	Benutzung vorhandener Mathematik-Biblioheken;

-	Geschwindigkeitssteigerung (insbesondere bei Schleifen);

-	Ansteuerung von (datenintensiver) Hardware, wie A/D und D/A-Karten;

-	Benutzung der Windows-API und von Klassenbibliotheken.

Von Nachteil ist:

-	MATLAB benutzt ein Thunking-System; jeder Aufruf der DLL erfordert von MATLAB die Bereitstellung geeigneter 16-bit-Aliasdeskriptoren für die innerhalb von MATLAB liegende 32bittrige Welt (darum braucht sich die DLL jedoch nicht zu kümmern). Bisweilen gehen nach einigen tausend Aufrufen die Selektoren zu Ende.

-	Mathematikfunktionen sind in MATLAB leichter formulierbar.

Normalerweise werden diese DLLs mit Fortran- oder C-Compilern und einer relativ großen statischen Linkbibliothek erstellt. Der Ansatz der Pascal-MEX-Programmierung vollzog sich in 2 Schritten:

-	Abtrennung der statischen Bibliotheken vom potentiellen Pascal-MEX-Programm in eine eigenständige, universell verwendbare DLL mit Eintrittspunkten in Pascal- (also Windows-) Aufrufkonvention (in Borland C);

-	Erstellung einer geeigneten Importbibliothek (in Borland Pascal bzw. Delphi sowie Borland C).

Folgende Ziele sollen mit Pascal-MEX-Programmen mit dieser DLL anvisiert werden:

-	Erschließung der Programmiersprache Pascal für MEX-Programme;

-	Vereinfachter Programmierzyklus in integrierten Entwicklungsumgebungen;

-	Kleinere MEX-Programme zur Schonung von Festplatten- und Hauptspeicherplatz;

-	Benutzbarkeit von Delphi und seiner Klassenbibliotheken.

Das Debuggen dieser DLLs erfolgt am einfachsten, indem zu Beginn von mexFunction ein fester Breakpoint (asm int 3 end) eingebaut wird. MATLAB selbst wird im Windows-Debugger gestartet.


Struktureller Aufbau von Pascal-MEX-Programmen

Dieses Rahmenprogramm dient als Startpunkt für jedes Pascal-MEX-Programm. Die Parameterliste von mexFunction muß (bis auf die Namensgebung) unbedingt beibehalten werden. Der Export der drei Einsprungpunkte darf ebenfalls nicht geändert werden.

library example; {$N+,E-} {MATLAB setzt ohnehin Koprozessor voraus}
uses pasmex,winprocs,wintypes;

procedure mexFunction(nlhs:Integer; var plhs:TMatArr;
  nrhs:Integer; const prhs:TMatArr); export;
 begin
{hier kommt die eigentliche MEX-Funktion hin}
 end;

exports
 set_entry_point index 2,
 mexFunction     index 3,
 mexAtExitFcn    index 4;

begin	{hier Initialisierung der DLL (meist unnötig)}
end.


Pascal-MEX-Programmbeispiel

Dieses Beispiel meldet sich zunächst mit einer Windows-MessageBox. Danach gibt es mittels mexVPrintf Informationen über die Übergabeparameter aus. Dabei stellt sich heraus, daß die Ergebnisvariablen noch nicht per Name "ergreifbar" sind, das Feld plhs ist schlichtweg leer.

library example; {$N+,E-} {MATLAB setzt ohnehin Koprozessor voraus}

uses pasmex,winprocs,wintypes;

procedure mexFunction(nlhs:Integer; var plhs:TMatArr;
  nrhs:Integer; const prhs:TMatArr); export;

 var	{Struktur für mexVPrintf}
  vsrec: record
   resc: Integer;
   resn: PChar;
   argc: Integer;
   argn: PChar;
  end;

 begin
  asm int 3 end;	{Turbo-Debugger-Break}
  MessageBox(hWndMATLABCmd,'Hallo Welt','Hi',MB_OK);
  vsrec.resc:=nlhs;
  vsrec.resn:=mxGetName(plhs[0]);
  vsrec.argc:=nrhs;
  vsrec.argn:=mxGetName(prhs[0]);
  mexVPrintf('Hallo Welt!'#10+
    'Ergebnisse: %d, Name erstes: %s;'#10+
    'Parameter: %d, Name erster: %s',vsrec,sizeof(vsrec));
 end;

exports
 set_entry_point index 2,
 mexFunction     index 3,
 mexAtExitFcn    index 4;

begin
end.


Die Struktur TMatrix

Normalerweise benötigen Sie niemals Direktzugriffe auf die Matrix-Struktur, das erledigen die mxXXX-Routinen komfortabel und portabel. Dennoch zum besseren Verständnis die Aufschlüsselung der Komponenten dieser Struktur:

const
 mxMAXNAM	=20;
 mxMAXTAG	=4;
 mxMAXDIM	=2;

type
 HPDouble=^Double;	{Symbolischer Huge-Zeiger}
 TDblArr=array[0..8190]of Double; {solange <64K}
 HPLongInt=PLongInt;	{Symbolischer Huge-Zeiger}
 TLongArr=array[0..16382]of LongInt; {solange <64K}

 PMatrix=^TMatrix;
 TMatrix=record
  name: array[0..mxMAXNAM-1] of Char;
  struc: LongInt;
  mtype: LongInt;
  dmode: LongInt;
  tag: array[0..mxMAXTAG-1] of Char;
  dim: array[0..mxMAXDIM-1] of LongInt;
  case integer of
  0: (pr: HPDouble;	{Huge Pointer!}
      pi: HPDouble;	{Huge Pointer!}
      nzmax: LongInt;
      jc: HPLongInt;	{Huge Pointer!}
      ir: HPLongInt);	{Huge Pointer!}
  1: (pra: ^TDblArr;	{Benutzungsvariante, falls kleiner 64K}
      pia: ^TDblArr;
      nzmaxa: LongInt;	{Füller}
      jca: ^TLongArr;
      ira: ^TLongArr);
 end;
 TMatArr=array[0..16382]of PMatrix;
{Symbolisches Array für plhs, prhs}

Weitere Konstanten rund um die Matrix:

const  	{Konstanten für Komponente struc}
 mxFULL     =0;
 mxSPARSE   =1;
 mxCOLON    =2;
 mxGLOBAL   =3;
 mxUNASSIGNED=4;
 mxCLEARMAT =5;
 mxUNASSARG =6;
 mxRHSUNASSIGNED=7;
 mxASSIGNED =8;
 mxSPAM     =9;
const  	{Konstanten für Komponente mtype}
 mxDOUBLE   =0;
 mxFLOAT    =1;
 mxLONGINT  =2;
 mxSHORTINT =3;
 mxUSHORTINT=4;
 mxUCHAR    =5;
const  	{Konstanten für Komponente dmode}
 mxNUMBER   =0;
 mxSTRING   =1;
const  	{Konstanten für Feldgrenzen}
 mxMAXNAM   =20;
 mxMAXTAG   =4;
 mxMAXDIM   =2;
const  	{Konstanten für mxCreateFull}
 mxREAL     =false;
 mxCOMPLEX  =true;
 mxIMAG     =true;


Die Struktur TEngine

Normalerweise benötigen Sie niemals Direktzugriffe auf die Engine-Struktur, das erledigen die engXXX-Routinen in portabler Weise. Dennoch zum besseren Verständnis die Aufschlüsselung der Komponenten dieser Struktur:

type
 PEngine=^TEngine;
 TEngine=record
  hgEngine:  THandle;
  hConvWithMatlab: HConv;
  UserFcn:   TFarProc;
  lTimeout:  LongInt;
  pszBuffer: PChar;
  iBufSize:  Integer;
 end;


Die Struktur TFile

Diese Struktur ist das Abbild der Borland-C-FILE-Struktur. Von Interesse ist wahrscheinlich das Dateihandle.

 PFile=^TFile;
 TFile=record
  level:    Integer;
  flags:    Word;
  fd:       Char;	{wohl das Dateihandle?}
  hold:     Char;
  bsize:    Integer;
  buffer,curp: PChar;
  istemp:   Bool;
  token:    Integer;
 end;

Weitere Konstanten und Typen für matXXX-Funktionen:

const
 matREAD    =0;
 matWRITE   =1;
 matAPPEND  =2;
type
 PMatFile   =Pointer;	{Keine genaueren Angaben}
 HPChar     =PChar;
 PPChar     =^PChar;


Hiermit sei die Möglichkeit ignoriert, auf PC-Plattformen auch 32bittrige REX-MEX-Dateien einsetzen zu können. Es ist anzunehmen, daß diese Variante im Zuge von Windows95 und seiner 32bit-DLLs ausstirbt.