MATHEMATICA TUTORIAL

MathLink Interface 3

The library now fully supports the Unicode character encoding forms UTF-8, UTF-16, and UTF-32. Use the following new API functions to put or get Unicode characters to or from a link.

	MLPutUTF8String()	MLGetUTF8String()
	MLPutUTF16String()	MLGetUTF16String()
	MLPutUTF32String()	MLGetUTF32String()
	MLPutUTF8Symbol()	MLGetUTF8Symbol()
	MLPutUTF16Symbol()	MLGetUTF16Symbol()
	MLPutUTF32Symbol()	MLGetUTF32Symbol()
	MLReleaseUTF8String()	MLReleaseUTF8Symbol()
	MLReleaseUTF16String()	MLReleaseUTF16Symbol()
	MLReleaseUTF32String()	MLReleaseUTF32Symbol()

The MathLink library header file mathlink.h no longer contains obsolete platform support sections such as those defined by MACINTOSH_MATHLINK or OS2_MATHLINK. MACINTOSH_MATHLINK definitions referred to Mac OS 9 and earlier. DARWIN_MATHLINK contains all platform-specific definitions for Mac OS X.

All uses of special alternative names for common C types have been removed from the API. The MathLink header file mathlink.h still contains versions of the API functions with these types for use with Interface 2 and older programs.

	Previous MathLink type	C type
	uchar_ct	unsigned char
	ucharp_ct	unsigned char *
	ucharpp_ct	unsigned char **
	ucharppp_ct	unsigned char ***
	ushort_ct	unsigned short
	ushortp_ct	unsigned short *
	ushortpp_ct	unsigned short **
	ushortppp_ct	unsigned short ***
	uint_ct	unsigned int
	uintp_ct	unsigned int *
	uintpp_ct	unsigned int **
	int_ct	int
	voidp_ct	void *
	voidpp_ct	void **
	charp_ct	char *
	charpp_ct	char **
	charppp_ct	char ***
	long_ct	long
	longp_ct	long *
	longpp_ct	long **
	long_st	long
	longp_st	long *
	longpp_st	long **
	ulong_ct	unsigned long
	ulongp_ct	unsigned long *
	kushortp_ct	const unsigned short *
	kushortpp_ct	const unsigned short **
	kuintp_ct	const unsigned int *
	kuintpp_ct	const unsigned int **
	kucharp_ct	const unsigned char *
	kucharpp_ct	const unsigned char **
	kcharp_ct	const char *
	kcharpp_ct	const char **
	kvoidp_ct	const void *

The memory allocator/deallocator functions passed to the library using MLSetAllocParameter() now must be thread-safe.

API functions that previously took a MLParametersPointer type as an argument or returned a MLParametersPointer type now instead take or return a char * type.

API functions that took as an argument or returned a mlapi_result type now take or return type int.

API functions that took as an argument or returned a mlapi_error type now take or return type int.

API functions that took as an argument or returned a mlapi_token type now take or return type int.

API functions that took as an argument or returned a mlapi_packet type now take or return type int.

API functions that took as an argument or returned a MLPointer type now take or return void *.

The MLOpen* functions previously took type long * for the error variable but now take type int *.

The header file mathlink.h now contains several new error definitions related to the Unicode character encoding forms.

	Error code	Interpretation
	MLEPDATABAD	MathLink encountered invalid character data in given character encoding
	MLEPSCONVERT	Unable to convert from given character encoding to MathLink encoding
	MLEGSCONVERT	Unable to convert from MathLink encoding to requested character encoding

MLPutMessage() and MLGetMessage() now use types int and int * respectively instead of the dev_message and dev_message * types.

MLSeekMark() and MLSeekToMark() now use type int rather than type long for the expression index.

The functions in the following table took long types for some arguments; they now take int.

	MLGetRawData()	MLGetData()
	MLGetArgCount()	MLGetRawArgCount()
	MLBytesToGet()	MLRawBytesToGet()
	MLExpressionsToGet()	MLTakeLast()
	MLPutRawSize()	MLPutRawData()
	MLPutArgCount()	MLPutComposite()
	MLBytesToPut()

MLGetReal() is now an actual API function rather than a #define alias to MLGetDouble(). MLGetReal() still has the same functionality as MLGetDouble().

MLActivate() is now an actual API function rather than a #define alias to MLConnect(). MLActivate() still has the same functionality as MLConnect().

The functions in column one listed below are now obsolete. New programs should use the functions listed in column two for replacement functionality.

	MLCheckFunction()	MLTestHead()
	MLCheckFunctionWithArg()	MLTestHead()
	MLGetShortInteger()	MLGetInteger16()
	MLGetInteger()	MLGetInteger32()
	MLGetLongInteger()	MLGetInteger64() for 64-bit integers or MLGetInteger32() for 32-bit integers
	MLGetFloat()	MLGetReal32()
	MLGetDouble()	MLGetReal64()
	MLGetLongDouble()	MLGetReal128()
	MLGetShortIntegerArrayData()	MLGetInteger16ArrayData()
	MLGetIntegerArrayData()	MLGetInteger32ArrayData()
	MLGetLongIntegerArrayData()	MLGetInteger64ArrayData() for 64-bit integers or MLGetInteger32ArrayData() for 32-bit integers
	MLGetFloatArrayData()	MLGetReal32ArrayData()
	MLGetDoubleArrayData()	MLGetReal64ArrayData()
	MLGetLongDoubleArrayData()	MLGetReal128ArrayData()
	MLGetShortIntegerArray()	MLGetInteger16Array()
	MLGetIntegerArray()	MLGetInteger32Array()
	MLGetLongIntegerArray()	MLGetInteger64Array() for 64-bit integers or MLGetInteger32Array() for 32-bit integers
	MLGetFloatArray()	MLGetReal32Array()
	MLGetDoubleArray()	MLGetReal64Array()
	MLGetLongDoubleArray()	MLGetReal128Array()
	MLDisownShortIntegerArray()	MLReleaseInteger16Array()
	MLDisownIntegerArray()	MLReleaseInteger32Array()
	MLDisownLongIntegerArray()	MLReleaseInteger64Array() for 64-bit integers or MLReleaseInteger32Array() for 32-bit integers
	MLDisownFloatArray()	MLReleaseReal32Array()
	MLDisownDoubleArray()	MLReleaseReal64Array()
	MLDisownLongDoubleArray()	MLReleaseReal128Array()
	MLGetIntegerList()	MLGetInteger32List(()
	MLGetRealList()	MLGetReal64List()
	MLDisownIntegerList()	MLReleaseInteger32List()
	MLDisownRealList()	MLReleaseReal64List()

	MLPutShortInteger()	MLPutInteger16()
	MLPutInteger()	MLPutInteger32()
	MLPutLongInteger()	MLPutInteger64() for 64-bit integers or MLPutInteger32() for 32-bit integers
	MLPutFloat()	MLPutReal32()
	MLPutDouble()	MLPutReal64()
	MLPutLongDouble()	MLPutReal128()
	MLPutShortIntegerArrayData()	MLPutInteger16ArrayData()
	MLPutIntegerArrayData()	MLPutInteger32ArrayData()
	MLPutLongIntegerArrayData()	MLPutInteger64ArrayData() for 64-bit integers or MLPutInteger32ArrayData() for 32-bit integers
	MLPutFloatArrayData()	MLPutReal32ArrayData()
	MLPutDoubleArrayData()	MLPutReal64ArrayData()
	MLPutLongDoubleArrayData()	MLPutReal128ArrayData()
	MLPutShortIntegerArray()	MLPutInteger16Array()
	MLPutIntegerArray()	MLPutInteger32Array()
	MLPutLongIntegerArray()	MLPutInteger64Array() for 64-bit integers or MLPutInteger32Array() for 32-bit integers
	MLPutFloatArray()	MLPutReal32Array()
	MLPutDoubleArray()	MLPutReal64Array()
	MLPutLongDoubleArray()	MLPutReal128Array()
	MLPutIntegerList()	MLPutInteger32List()
	MLPutRealList()	MLPutReal64List()

	MLGetUnicodeString()	MLGetUCS2String()
	MLGetUnicodeSymbol()	MLGetUCS2Symbol()
	MLPutUnicodeString()	MLPutUCS2String()
	MLPutUnicodeSymbol()	MLPutUCS2Symbol()
	MLPut16BitCharacters()	MLPutUCS2Characters()
	MLDisownUnicodeString()	MLReleaseUCS2String()
	MLDisownUnicodeSymbol()	MLReleaseUCS2Symbol()

Interface 3 changes the default link protocol for link mode Listen and link mode Connect links. By default the MathLink library will create "SharedMemory" links for link mode Listen and link mode Connect links on all platforms.

MORE ABOUT

Alphabetical Listing of MathLink C Functions

MathLink C Functions for Exchanging Expressions

MathLink C Functions for Exchanging Integers

MathLink C Functions for Exchanging Lists

MathLink C Language Functions