Initializes a 2D graphics window. If width and height are set to -1, the window is primarily used for vector graphics; if width and height are given they are specified in pixels - the window has then a preferred size and can always be reset to this size. Such a window is primarily used for pixel graphics, though pixel and vector graphics can be mixed. bkgnd sepcifies the background color, while fgnd specifies the default foreground color. Color values can be assembled with the MATHRGB(r,g,b) macro.

Return values:
0: success
non 0: failure.

Sets up the dimensions of a 2D graphics window. With this call the left, right, upper and lower border of the 2D drawing area can be defined.

Definition of GraphicsSetup2D:

struct GraphicsSetup2D
{
 double xMin ;
 double xMax ;

 double yMin ;
 double yMax ;
} ;

Return values:
none

Gets the current dimension of 2D graphics window. Left, right, upper and lower border as well as x and y tickmark distances are retrieved.

Definition of GraphicsSetup2D:

struct GraphicsSetup2D
{
 double xMin ;
 double xMax ;

 double yMin ;
 double yMax ;
} ;

Return values:
0: success
-1: no 2D graphics window open
non 0: other failure

Gets the width and height in pixels of the 2D graphics window. This call can be issued for both pixel or vector graphics oriented 2D windows. pwidth and pheight must point to storage that can hold a 32 bit integer each.

Return values:
0: success
-1: no 2D graphics window open
non 0: other failure

Sets the axis and grid that are displayed in the 2D window. Note: the user may change these values when doubleclicking in the 2D window via the 2D properties dialog.

Definition of GraphicsGridSetup2D:

struct GraphicsGridSetup2D
{
BOOL bDrawAxis ;
BOOL bDrawAxisLabels ;
BOOL bDrawBackGrid ;

double xOffset ;
double xTick ;
int xMajorTick ;
char *pszXLabel ;

double yOffset ;
double yTick ;
int yMajorTick ;
char *pszYLabel ;
}


Return values:
none

Gets the current axis and grid that are displayed in the 2D window.

Return values:
0: success
-1: no 2D graphics window open
non 0: other failure

Draws an axis cross. xOffset and yOffset allow to specify where the axis cross intersects; xTick and yTick allow to modify the current minor tick setting (Attention: this will modify the content of the GraphicsGridSetup2D - see above), while pszXLabel and pszYLabel allow to define the text label that is drawn for each axis. If pszXLabel is NULL, "x" is used as label for the x-axis; if pszYLabel is NULL, "y" is used as lable for the y-axis.

Return values:
none

Sets a pixel with the specified color at the location (x,y).

x and y are both interpreted to be integer pixel coordinates; the left, upper corner is (0,0) while the right lower corner is (with,height).

If bShowImmediate is true, the 2D graphics window will normally show the pixel immediately (if not switched off somewhere else).
If set to false, a bunch of SetPixels is executed at once, which may be much quicker, though it may not reveal the dynamic of the equation generating the pixels as well.

Return values:
none

Sets a single point at the location (x,y) with the default foreground color. x and y are transformed to the viewport according to the values set during a SetDimensions call.

Return values:
none

Sets a single point at the location (x,y) with the specified color. x and y are transformed to the viewport according to the values set during a SetDimensions call. Color values can be assembled with the MATHRGB(r,g,b) macro.

Return values:
none

Moves the current position (as used in LineTo) to the specified point (x,y).

Return values:
none

Draws a line from the current position as specified by either MoveTo or the last LineTo call to (x,y) in the default foreground color.

Return values:
none

Draws a line from the current position as specified by either MoveTo or the last LineTo call to (x,y) in the specified foreground color. Color values can be assembled with the MATHRGB(r,g,b) macro.

Return values:
none

Displays the specified text (pszText) at the logical coordinates x,y in a 2D view in the default foreground color. If width is given only the number of characters specified by width is displayed; if width = -1 (default), the string is assumed to be 0-terminated.

Return values:
none

Displays the specified text (pszText) at the logical coordinates x,y in a 2D view in the specified color. If width is given only the number of characters specified by width is displayed; if width = -1 (default), the string is assumed to be 0-terminated. Color values can be assembled with the MATHRGB(r,g,b) macro.

Return values:
none

Displays the specified rectangle with the given width and height at the logical coordinates x,y (lower left corner) in a 2D view in the default foreground color. If bFilled is TRUE, the rectangle will be drawn as a filled block.

Return values:
none

Displays the specified rectangle with the given width and height at the logical coordinates x,y (lower left corner) in a 2D view in the specified color. If bFilled is TRUE, the rectangle will be drawn as a filled block. Color values can be assembled with the MATHRGB(r,g,b) macro.

Return values:
none

Displays the specified ellipse with the given width and height at the logical coordinates x,y (center) in a 2D view in the default foreground color. If bFilled is TRUE, the ellipse will be drawn filled.

Return values:
none

Displays the specified ellipse with the given width and height at the logical coordinates x,y (center) in a 2D view in the specified color. If bFilled is TRUE, the ellipse will be drawn filled. Color values can be assembled with the MATHRGB(r,g,b) macro.

Return values:
none

Displays the specified circle with the given radius at the logical coordinates x,y (center) in a 2D view in the default foreground color. If bFilled is TRUE, the circle will be drawn filled.

Return values:
none

Displays the specified circle with the given radius at the logical coordinates x,y (center) in a 2D view in the specified color. If bFilled is TRUE, the circle will be drawn filled. Color values can be assembled with the MATHRGB(r,g,b) macro.

Return values:
none

Sets the current background color in a 2D window. The default is black or as specified during InitGraphics.

Return values:
none

Sets the current foreground color in a 2D window. All 2D primitives drawn afterwards without a color specification as well as the axis cross and grid will be drawn in this color

Return values:
none

Sets the current color in a 2D window. All 2D primitives drawn afterwards without a color specification will be drawn in this color

Return values:
none

Completely clears the screen (both 2D graphics and 3D graphics), thereby removing all pixels, points, lines and other graphical primitives.

Return values:
none

Triggers a repaint of the screen (both 2D graphics and 3D graphics). This function is mainly useful, if the automatic screen refresh every 250 milliseconds has been disabled - with this functionality the MLL has fine grained control over when to display what. (can be used for animations)

Return values:
none

This function allows to switch the automatic screen refresh on and off (if bTrue is TRUE, screen refresh is enabled; if it is FALSE screen refresh is disabled). Automatic screen refresh happens every 250 milliseconds and displays all the graphics primitives drawn so far - this will usually not result in a smooth animation of the progress, but a bulk update. This mode of operation is a good compromise between speed and interactivity. To get even more speed, switch the screen refresh off completely and call RefreshScreen only once when the whole calculation is completed. To get a smooth animation, also switch automatic screen refresh off and call RefreshScreen everytime an animation frame is completed.

This function works on both 2D and 3D graphics windows.

Return values:
none

This function converts the integer pixel coordiantes (x,y) to the viewport relative double coordinates (*px,*py) - the viewport beeing defined by SetDimensions. px and py must point to storage that can hold 8 byte IEEE doubles.

Return values:
0: success
-1: no 2D graphics window open
non 0: other failure

This function converts the viewport relative double coordinates (x,y) to the integer pixel coordinates (*px,*py). - the viewport beeing defined by SetDimension. px and py must point to storage that can hold 32 bit integers.

Return values:
0: success
-1: no 2D graphics window open
non 0: other failure

This function allows to apply a world transformation to a 2D graphics window by specifying an angle around which the whole 2D graphics output is to be rotated. The axis cross (if present) is not transformed. The rotation happens around the point specified by (rCenterX,rCenterY); the angle phi must be specified in rad, where 2*pi is a rotation around 360° .

Return values:
none

This function allows to apply a world transformation to a 2D graphics window by specifying a 2D vector (x,y) by which all graphics primitives are translated. The axis cross (if present) is not transformed.

Return values:
none

This function adds the specified text to the console window. For a more convenient interface use the wout stream based console output, by defining MATH_IOSTREAM before including MathEnv.h, and calling:

wout.SetEnv( pEnv ) ;

in the MathEntry procedure.

Use wout just like cout. E.g.:

wout << "Hello world...some data: " << 4711 << endl ;

Console output is asynchronous in every case; normally the console output goes to the console window only, from which it will be discarded after a certain maximum number of lines is reached (default is around 1000 lines). If you want to save the console output permanently, use the "Tools" / "Log To File" menu and specify a logfile name. Everything that has been written to the console so far and all further output is the dumped to this logfile.

Return values:
none

This function reads one line from the console; when it is invoked, a console input line appears at the bottom of the console window; as soon as the user presses enter in this line the input is transferred to the buffer specified by pszText whose size must have been specified in iBufSize.If the buffer contained already 0-terminated text before ConsoleRead was called, this text will be displayed in the input line as default input.

Return values:
0: success
non 0: failure

This function allows for synchronous output: it displays a messagebox and stops MLL execution until the user commits or cancels the message. Various types of message boxes are possible:

SP_OK	a messagebox with on ok button
SP_OKCANCEL	a messagebox with an ok and a cancel button
SP_ABORTRETRYIGNORE	a messagebox with an abort, a retry and an ignore button
SP_YESNOCANCEL	a messagebox with a yes, a no and a cancel button
SP_YESNO	a messagebox with a yes and a no button
SP_RETRYCANCEL	a messagebox with a retry and a cancel button

The return value can be one of:

SPRC_OK	Ok was selected
SPRC_CANCEL	Cancel was selected
SPRC_ABORT	Abort was selected
SPRC_RETRY	Retry was selected
SPRC_IGNORE	Ignore was selected
SPRC_YES	Yes was selected
SPRC_NO	No was selected

This function displays a parameter editing dialog, if bInit is TRUE, that is defined by the XML DAT file specified in pszDatFile. If pszDatFile is NULL, a DAT file with the same name as the MLL but with the extension .DAT is searched for the definition of the parameters. If bInit is FALSE, no dialog is displayed. In any case, a pointer to a MathParam object is returned, that can be queried for the parameter values that the user entered. The MathParam object need not and must not be deleted - the system takes care for the memory.

Return values:
An allocated MathParam interface. This interface supports the following functions:

void GetValue( char *pszName, char *pszBuf, int sizeOfBuf );	gets an arbitrary string value
int GetValueInt( char *pszName );	gets an integer value
double GetValueDouble( char *pszName );	gets a float value
BOOL GetValueBool( char *pszName );	gets a boolean value; the user may either enter "yes" or "true" (caseinsensitive) for a boolean true or "no" or "false" (caseinsensitive) for a boolean false
MATHCOLOR GetValueColor( char *pszName );	gets an RGB color value triple; the value may be entered as "R,G,B" (with delimiting commas) or via a color selection dialog
int GetNumberOfKeys();	gets the number of all paramters specified in the DAT file
void GetKey( int i, char *pszBuf, int sizeOfBuf );	gets the name of the i'th parameter specified in the DAT file.
int GetValueLen( char *pszName );	gets the length of a value specified by name.
void GetValueMatrix( char *pszName, MathMatrix &matrix );	gets the parameter with name pszName as matrix object. Formulas in the matrix will be evaluated left to right, top to bottom as necessary to yield a matrix of double values. If formula evaluation is not necessary, the whole matrix can be fetched in string form via GetValue(pszName,pszBuf,sizeOfBuf). The matrix will manage its memory automatically and should preferably be allocated as stack object.

This function adds a new custom menu to the Tools menu pulldown; pszMenuText contains the text to be displayed; iCommandCode contains the commandcode that will be sent to the MathEntry routine of the MLL every time the menu is selected.

Return values:
none

This function asks the runtimesystem whether or not the MLL processing should stop, because a break was requested by the user or the system. This break can be triggered either by the use selecting the Break menu or by trying to close one of the MLLs windows or by closing the whole MathFrame.

Furtheron, if the user requested Pause, the function will not return until Pause was selected once again, or an additional Break Request happened.

This function should therefore be called and the return value checked by all MLLs in lengthy loops.

Return values:
0: no break request
1: yes, break was requested

This function pauses the MLL execution for the specified number of milliseconds - it is most useful for predictable timing during playing animation loops.

Return values:
none

This function sets the MLL to the pause mode as if the user requested Pause - MLL execution is halted, and the titlebar will display a blinking PAUSED message. This function is especially useful for debugging MLLs in single steps.

Return values:
0: success
non 0: failure

This function retrieves the number of currently set markers; it will be returned in *piNumber. piNumber must be a pointer that points to storage that can hold a 32bit integer.

Return values:
0: success
-1: no 2D graphics window open
non 0: other failure

This function gets the x and y coordiantes of the marker specified by the index iMarkerIndex. iMarkerIndex is allowed to be in the range from 0 to (*piNumber-1) as returned from GetNumberOfMarkers (inclusive range)

The positions are returned in *px and *py and are meant to be viewport coordinates. px and py must point to storage that can hold 8byte IEEE double values.

Return values:
0: success
-1: no 2D graphics window open
non 0: other failure

This function removes all markers from system memory and the display.

Return values:
none

This function adds a new marker at viewport coordiantes (x,y)

Return values:
none

This function allows to change the position of a marker. The marker is identified by its index, that can be in the range 0 to (*piNumber-1) as returned by GetNumberOfMarkers. (inclusive range)

The new position is specified as double viewport coordinates (x,y).

Return values:
none

This function clears the variable dictionary for the expression parser.

Return values:
none

This function sets a new named double variable. If necessary storage is allocated for the variable, whose name is specified in "pszVarName" and whose double value is specified in "value". *key contains an integer after the function returns that can be used to access and change that variable quickly by using the SetVariableByKey function. key must be a pointer that points to storage that can hold a 32bit integer.

Return values:
0: success
non 0: failure

Given the key that identifies a variable that was set by "SetVariable", changes the double value of that variable to "value". This function should be used to change the value of a variable instead of calling SetVariable again and again, since it is much quicker.

Return values:
none

Given a mathematical expression specified in pszExpression, that can contain named variables (whose value was set before by the SetVariable calls), returns a double value that is the result of the expression evaluation in *pResult. pResult is a pointer that points to storage that can hold an 8byte IEEE double value.

Attention: this is currently not supported in a remote client.

The following operators are currently supported in the expression:

+	add
-	subtract
*	multiply
/	divide
^	power; "x^y" is shortcut notation for pow(x,y)
<	1 if x<y, 0 if x>=y
>	1 if x>y, 0 if x<=y
=	1 if x equals y, 0 otherwise
;	sequence operator; delimits a subexpression
:	defines a variable to the left with the subexpression to the right; e.g.: r:sqrt(x^2+y^2);sin(r)/r;

The following functions are currently supported in the expression:

Name	Description	Usage	Arguments
sin	Sinus	sin(x)	x: angle in rad
cos	Cosinus	cos(x)	x: angle in rad
tan	Tangens	tan(x)	x: angle in rad
asin	Arcus Sinus	asin(x)	x: arcus length
acos	Arcus Cosinus	acos(x)	x: arcus length
atan	Arcus Tangens	atan(x)	x: arcus length
exp	Exponential function (e^x)	exp(x)	double x
log	Natural Logarithm	log(x)	double x
sqrt	Square Root	sqrt(x)	double x
j0,j1,jn	Bessel functions of first kind	j0(x),j1(x),jn(n,x)	double x, int n
y0,y1,yn	Bessel functions of second kind	y0(x),y1(x),yn(n,x)	double x, int n
fact	Factorial (x!)	fact(x)	integer x
mod	x Modulo y	mod(x,y)	integer x, integer y
pow	Power	pow(x,y)	double x, double y
time	The time in seconds since program start	time(-1 or 0 or 1)	-1: time when expression evaluation was started 0: time when mll evaluation was started 1: current time
rand	a random value in [0,1]	rand()
abs	absolute value	abs(x)	double x
floor	the next smaller integer	floor(x)	double x
ceil	the next bigger integer	ceil(x)	double x
if	Conditional function	if(boolexpr,x,y) e.g.: if(x=0,1,sin(x)/x)	boolexpr: true|false; e.g. x<10 double x double y

Return values:
0: success
non 0: failure

This function initializes the 3D graphics window. At any given time there can be at max 1 such window. bkgnd is the default background color; fgnd is the default foreground color; width and height are a hint for the window size in pixels.

The coordinate system of the 3D window will be like:
x axis horizontal, positive to the right
y axis vertical, positive to the top
z axis normal to the screen plane, positive outwards (to the viewer)

The 3D window that will be opened uses OpenGL for rendering; depending on the local installation this may either be a software renderer or a hardware accelerated renderer - consult your graphics card driver manual for details.

Return values:
0: success
non 0: failure

This function creates a new point in 3D space at position (x,y,z) with the default color.

Return values:
none

This function creates a new point in 3D space at position (x,y,z) with color fgnd. The MATHRGB macro can be used to assemble a color value out of red, green, blue components.

Return values:
none

This function moves the current position in 3D space to (x,y,z). The current position will be used and updated as well by the LineTo3D functions.

Return values:
none

This function creates a line in 3D space from the current position (as set by MoveTo3D or the last LineTo3D call) to (x,y,z) with the default foreground color.

Return values:
none

This function creates a line in 3D space from the current position (as set by MoveTo3D or the last LineTo3D call) to (x,y,z) with the foreground color fgnd. The MATHRGB macro can be used to assemble a color value out of red, green, blue components.

Return values:
none

This function creates a triangle polygon in 3D space. Edgepoints are: (x1,y1,z1) (x2,y2,z2) (x3,y3,z3). A normal vector will be calculated automatically that is perpendicular to the plane defined by the 3 edgepoints. (necessary if lighting is switched on). The color is the default foreground color. Currently only flat shading is possible with this function.

Return values:
none

This function creates a triangle polygon in 3D space. Edgepoints are: (x1,y1,z1) (x2,y2,z2) (x3,y3,z3). A normal vector will be calculated automatically that is perpendicular to the plane defined by the 3 edgepoints. (necessary if lighting is switched on). The color is defined by fgnd. The MATHRGB macro can be used to assemble a color value out of red, green, blue components. Currently only flat shading is possible with this function.

Return values:
none

This function sends a 3D vertex to the MathFrame server which can later be used in SetIndexedTriangle3D. The order in which SetVertex3D is called determines the index that must later be used when referring to these vertices.

Return values:
none

This function creates a triangle polygon in 3D space. Edgepoints must have been defined earlier on via SetVertex3D; only the 0-based index of the 3 edges is sent. A normal vector will be calculated automatically that is perpendicular to the plane defined by the 3 edgepoints. (necessary if lighting is switched on). With this function it is possible to share vertices between triangles which allows for smooth shading as well (can be specified in 3D Properties window). The color is defined by fgnd; if left out the default foreground color will be used. The MATHRGB macro can be used to assemble a color value out of red, green, blue components.

Return values:
none

This function draws a quad polygon in 3D space. This is done by decomposing the quad to 2 triangles - the function is a convenience function that automatically does so and conceptually calls SetTriangle3D. See SetTriangle3D for details.

Return values:
none

This function draws a quad polygon in 3D space. This is done by decomposing the quad to 2 triangles - the function is a convenience function that automatically does so and conceptually calls SetTriangle3D with a color argument (fgnd). See SetTriangle3D for details.

Return values:
none

3D Higher order primitives

This function draws a sphere in 3D space at position (x,y,z), with radius r and a tesselation detail as defined by iTess. iTess = 16 (the default) gives already nicely rounded spheres. The sphere color is defined by the default foreground color. Spheres are always smooth shaded (if lighting is enabled)

Return values:
none

This function draws a sphere in 3D space at position (x,y,z), with radius r and a tesselation detail as defined by iTess. iTess = 16 (the default) gives already nicely rounded spheres. The sphere color is defined by fgnd. The MATHRGB macro can be used to assemble a color value ot of red, green, blue components. Spheres are always smooth shaded (if lighting is enabled)

Return values:
none

This function displays the text specified in pszText at position (x,y,z). If width is left out or set to -1, the pszText is assumed to be 0-terminated. The text color is defined by fgnd; if left out the default forergound color will be used. The MATHRGB macro can be used to assemble a color value ot of red, green, blue components.

Return values:
none

This function draws a cubus in 3D space at position (x,y,z), with the specified width, height and depth. The color is defined by fgnd; if left out the default foreground color will be used. The MATHRGB macro can be used to assemble a color value ot of red, green, blue components.

Return values:
none

3D World transformation

This function defines a rotation around (0,0,0) with the euler angles phi, rho, theta. The angles must be specified in rad. phi ranges from 0 to 2*pi; rho from -pi/2 to pi/2 and theta from 0 to 2*pi. The so defined rotation is applied to all points, lines, polygons and higher order primitives, but not to the axes cross - it is assumed to be a world transformation of the defined geometry; not a view transformation.

Return values:
none

This function defines a translation about the vector (x,y,z). The so defined translation is applied to all points, lines, polygons and higher order primitives, but not to the axes cross - it is assumed to be a world transformation of the defined geometry; not a view transformation.

Return values:
none

This function draws a 3D axis cross - with its default settings it draws a red x axis, green y axis and blue z axis. The parameters in detail:
BOOL xAxis: if TRUE, x axis will be drawn
BOOL yAxis: if TRUE, y axis will be drawn
BOOL zAxis: if TRUE, z axis will be drawn
double axisLen: the length of all 3 axises - 1.0 is a reasonable default
double arrowSize: the length of the arrows at the end of the axis lines. 0.05 look good together with axisLen 1.0
pszXLabel, pszYLabel, pszZLabel: the texts to print at the end of the axis lines. If these parameters are NULL, "x", "y" and "z" are printed
MATHCOLOR xColor: color of x axis
MATHCOLOR yColor: color of y axis
MATHCOLOR zColor: color of z axis

Return values:
none

This function sets various parameters that define the 3D view, like the camera position, the lookAt point, the far and near z clipping planes, whether or not pseudo realistic lighting should be used, and what the color and intensity of the 3 point standard light setup is (if lighting is used). This is the according definition of GraphicsSetup3D:

struct GraphicsSetup3D
{
unsigned short size ;

float cam_x ; // view
float cam_y ; // view
float cam_z ; // view

float lookAt_x ; // view
float lookAt_y ; // view
float lookAt_z ; // view

float znear ; // view
float zfar ; // view

bool bLighting ;
MATHCOLOR colorLight1 ;
MATHCOLOR colorLight2 ;
MATHCOLOR colorLight3 ;
BOOL bSmoothShadeShared ;
BOOL bShowBoundaries ;

GraphicsSetup3D() { size = sizeof( *this ) ; }
} ;

Return values:
none

Get the current definitions of the 3D view. See the description of GraphicsSetup3D in "SetView3D".

Return values:
0: success
-1: no 3D graphics window open
non 0: other failure

Gets the actually displayed number of 2D primitives. The kind of object to be counted is specified as iObjectType; currently the following objects are recognised:
#define MATH_OBJ_TYP_POINT 1
#define MATH_OBJ_TYP_LINE 2
#define MATH_OBJ_TYP_POLYGON 3

The result is returned in the variable *piNumber; it must point to a 32 bit variable allocated by the caller.

Return values:
0: success
-1: no 2D graphics window open
non 0: other failure

Sets the maximum number of 2D primitives to be displayed. If the maximum is reached, last recently inserted objects are removed (FIFO). The kind of object for which this limit is to be set is specified as iObjectType; currently the following objects are recognised:
#define MATH_OBJ_TYP_POINT 1
#define MATH_OBJ_TYP_LINE 2
#define MATH_OBJ_TYP_POLYGON 3

Currently the default for all objects is: 262400
To change this default, edit (or insert) the following registry key:
HKEY_CURRENT_USER\Software\MATHLIB\MathFrame\Settings\General\MaxGraphicsObjects

Return values:
none

Gets the actually displayed number of 3D primitives. The kind of object to be counted is specified as iObject3DType; currently the following objects are recognised:
#define MATH_OBJ_TYP_POINT3D 10
#define MATH_OBJ_TYP_LINE3D 11
#define MATH_OBJ_TYP_TRIANGLE3D 12

The result is returned in the variable *piNumber; it must point to a 32 bit variable allocated by the caller.

Return values:
0: success
-1: no 3D graphics window open
non 0: other failure

Sets the maximum number of 3D primitives to be displayed. If the maximum is reached, last recently inserted objects are removed (FIFO). The kind of object for which this limit is to be set is specified as iObject3DType; currently the following objects are recognised:
#define MATH_OBJ_TYP_POINT3D 10
#define MATH_OBJ_TYP_LINE3D 11
#define MATH_OBJ_TYP_TRIANGLE3D 12

Currently the default for all objects is: 262400
To change this default, edit (or insert) the following registry key:
HKEY_CURRENT_USER\Software\MATHLIB\MathFrame\Settings\General\Max3DGraphicsObjects

Return values:
none

If an error occured during the previous function call, a descriptive error text may be fetched with this function; the caller must allocate the buffer memory of the buffer pszErrorTextBuf and provide the size in iErrorTextBufSize. The error code of the last error is returned as return value of the function. The error code and message are dangling, meaning that successfull function invocations do not delete them - it is therefore possible to execute a batch of primitives and afterwards ask with GetLastError() whether or not any failed.

Return values:
the last error code