How does an API work?

For the API, all of these products are developer tools. Most are intended for .NET, or Java developers. Some can be used from other languages like Perl, PHP, or Visual Basic. The way most of them work goes something like this:

  • Create some main object using the software.
  • Set values like
       obj.Title = "My Graph" and
       object.XaxisFontSize = 8
  • Set data in loops that resemble closely what you do with the DesignBais graph – you loop on data, adding it into the object
  • "Render" the object

The API for components is always defined in documentation. The internet is an excellent resource for examples, comments, bug info, etc. Sound familiar? We do the exact same thing when we get info from the manual to build the OUTPUT.zz variables in DesignBais.

That "rendering" part bears some more inquiry. Off hand I’ll say we’re talking about three different ways to render data. (Lot of lists here, eh? )

  1. With DesignBais, we create a dynamic array. On the web server, DesignBais code parses through our data, grabs what it needs, and loads the OWC object according to its specific API. This is a hardcoded process and we can’t substitute components. (This is done in bachart.asp, and no, the code is obfuscated so we can’t see it.)
  2. After population with data, the object is instructed to generate the chart as an image. The image is saved to disk as a file – JPEG, GIF, PNG, etc. ( I’ll bet some lights just went on! ) In particular, DB renders graphs as GIF images.
  3. OR… we can create a little web page which renders the graph into the page. I don’t suppose you’ve read my article on Client-side scripting, IFRAMEs, etc? Any more light bulbs?

Using the API

How do we get data into the API? Where does this "object" thing come from? Can we do this in BASIC? Wow, you ask a lot of questions! The answer is to do some coding outside of the MV environment. Data can be provided to the code in various ways. ( Oh no, not another list ! )

  • Write the data from MV to disk using OPENSEQ, D3 OSFI, or by whatever means you usually do this sort of thing. Most of us have written data to the host file system for email, FAX, or other purposes. The data can be tab delimited, XML, or formatted any way you want.. Once the data is written to disk, you can Execute or Perform a command to startup your graph-generating program which will:
    • create the object
    • read the data, parse it for individual values, and load the object 
    • render to an image file or to HTML
  • You can use tools like mv.NET, UniObjects, UniObjects for Java, QMClient, or the D3 Class Library to reach from the web server into your MV environment to pull out the data.

All of the components listed above have a different API. Some of them must be dropped onto an ASP.NET web form and populated by .NET code (VB.NET, C#, etc). Some are ActiveX controls that must be dropped onto an HTML web page. Again, this doesn’t matter, as long as the process can be automated from start to finish.

Getting the graph into DesignBais

This is the simple part. If the only way to display the graph is to use HTML (rare case) then you can use the technique documented for client-side scripting and just put a little HTML page into your DesignBais form via a Text Only field. More commonly an API will have a Save function which allows for saving to disk. Create a unique ID, save the image to the web server and use DBIMAGESPEC to change the name of an Image field on a form so that it points to your new image. (We can’t use an absolute address for an image. All image references are relative to the DB virtual directory, \images. Otherwise you wouldn’t even need to save the image to the web server.)

Sometimes you need to work indirectly to get what you need from components like this. For example, I don’t think the jGRAPH component has a SaveAsJpeg type of feature, but once the graph is generated in the object it is as a Java BitmapImage, and that can be saved to disk. As you can see, the path taken for each one may be slightly different but the end result is the same.

You’ll need some housekeeping method to remove old images from disk. You might choose to create a directory for each user and clear it whenever the user logs in or out. You might use filenames with a date/time stamp and purge images older than some number of minutes or hours. DesignBais has a SESSION.ID variable that doesn’t change while a give user is logged-in – you may want to consider using that. You’ll need to work this out on an as-needed basis – it’s a lot like select lists which go "stale" and need to be cleared.