The Mathematica Journal
Departments
Download This Issue
Home
Feature Articles
Graphics Gallery
Tricks of the Trade
In and Out
Columns
The Mathematica Programmer
New Products
New Publications
Classifieds
Calendar
News Bulletins
Editor's Pick
Mailbox
Letters
Write Us
About the Journal
Staff and Contributors
Submissions
Subscriptions
Advertising
Back Issues

C++ Code Comments

Exercise Maker is written in C++, and all issues related to MathLink are encapsulated in the TMathLink class, which mediates the connection providing a "higher" level interface to the kernel for the rest of the code. The idea for that originates in DensityViewer--A MathLink Example Program in C++ [3]. Although our code is also in C++, anyone who knows C should be able to read the code and reuse it with minor modifications. We choose to present here the foundation of the TMathLink class; that is, simple routines which make it possible to examine the relatively complex exerciseList. They are called very often by other higher level routines that comprise the actual interface of the TMathLink class. The whole source code of the TMathLink class is included in the additional material.

To begin with, we need to refer to parts of the list in order to get their dimensions or their values. Roughly, what we need is a flexible C counterpart of the Part function. Suppose we would like to refer to Part[exerciseList,1,2]. There are several ways to do that. The easiest (although not very flexible) way seems to be

[Graphics:../Images/index_gr_15.gif]

The kernel will first parse the string given as the second argument into an expression, then evaluate it and finally send back the result of the evaluation. Although this method is quite handy in some cases, it is not flexible in the sense that we cannot process many parts with the same code, for example, by wrapping this statement in a loop or by calling it as a subroutine. We can do that if we specify the parts with variables of the C program rather then hardcoding them in a string. Since we have to refer to parts that have different depths in exerciseList, our part specification routine should accept a variable number of indices. One flexible implementation is to keep the part specification in an array which is declared according to the calling routine needs. So, the arguments of our SpecifyPart method are (a pointer to) the array itself and the number of indices stored in it. To specify the same part as before, we can make a call like

[Graphics:../Images/index_gr_16.gif]

where SpecifyPart is implemented as follows

[Graphics:../Images/index_gr_17.gif]

SpecifyPart is a member function of TMathLink, and it is called by many other member functions that wrap it inside other MathLink routine calls to specify what function they want to apply to the part being referred to and to fetch the result. One example of such a function is GetStringAt, which puts ToString before the part specification. It is very often used since all of the attributes of the objects are fetched from the link as strings.

[Graphics:../Images/index_gr_18.gif]

In the MathLink conversation between the front end and the kernel, the former is the active side. The front end sends requests to the kernel and fetches the results after they are sent back by the kernel. For consistency, we wrap all our requests to the kernel between two MathLink calls as in GetStringAt.

[Graphics:../Images/index_gr_19.gif]

Indeed, MLEndPacket is absolutely necessary to mark the end of the packet and trigger the actual evaluation. The kernel responds to any request like this by sending the result wrapped in ReturnPacket. Since we always know in advance the type of the result, i.e., the expression in the ReturnPacket, all fetch methods are quite simple. For instance, FetchString tries to get a string from the ReturnPacket.

[Graphics:../Images/index_gr_20.gif]

Since there might be other packets (such as MessagePackets) before the ReturnPacket, the function simply skips them. If what is in the ReturnPacket is not a MLTKSTR, FetchString discards it and returns NULL, so the caller can realize that something went wrong. By calling MLNewPacket after that, FetchString discards the rest of the ReturnPacket leaving the link ready for new requests. All the methods described so far are from the low level foundation of the TMathLink class. They are defined as protected member functions and are not called from outside TMathLink. The interface methods are higher level routines that issue more specific requests, quite often making use of the lower level routines. An example of such a method is

[Graphics:../Images/index_gr_21.gif]

which uses GetStringAt to retrieve the type of the ith object in the answer template.


Converted by Mathematica      October 5, 1999

[Prev Page][Next Page]