Page Comparison

The first thing you need to do in order to begin using either of the two main CFMumps APIs is to open a connection to the MUMPS database. Unlike the MUMPS language, where your connection to the database is implicit and automatic, the CFML and CFScript environments require you to initiate and terminate this connection explicitly. Although this requires a couple of extra steps, it does not significantly expand the number of lines of code your application will use, as you can open the database, perform as many database operations as you preferneeded, and then close the database. You do not have to open and close the database for each operation individually.

This connection model introduces some interesting flexibility: it allows us to implement the CFMumps connectors either directly, via an in-process binding, or indirectly, over a TCP socket, the latter of which is much slower, but allows your application and your MUMPS database to be located on separate servers.

Let's look at the connection model for each of the two major CFMumps APIs.

Connecting with the Basic API

With the basic API, you access the MUMPS database with familiar methods, including but not limited to get, set, kill, data, and order. These operations should be familiar to you as a MUMPS programmer. However, in order to begin using these API methods, you need a connection to the MUMPS database.

In this example, you will create an instance of lib.cfmumps.mumps, open the database, fetch the value of ^people("Smith,Joe","birthday") into a CF variable, write it to the page, and close the database.

var db = createObject("component", "lib.cfmumps.mumps");
db.open();

var joeBirthday = db.get("people", ["Smith,Joe","birthday"]);
writeOutput("Joe's birthday is " & joeBirthday);

db.close(); 

<cfset db = createObject("component", "lib.cfmumps.mumps");
<cfset db.open()>

<cfset var joeBirthday = db.get("people", ["Smith,Joe", "birthday"])> 
<cfoutput>#joeBirthday#</cfoutput>

<cfset db.close()> 

You should not attempt to either re-open an already opened database, nor close one that's already closed. As a safeguard against this, the isOpen() method will return true if the database has already been opened, or false otherwise.

Connecting with the Global API

The Global API lets you project MUMPS globals to native CF structures, and vice versa, as well as providing a few other operations like value, defined, and delete. Like the Basic API, the Global API exposes an open() method, but that method–unlike its argumentless Basic API counterpart–requires you to specify up-front the global on which the object will operate, as well as options controlling atomicity.  

In this example, you will use the Global API to open a reference to ^DD(200) and fetch all of its data and child subscripts into the CFML variable newPersonFile:

var global = createObject("component", "lib.cfmumps.global");
global.open("DD", [200]); 

var newPersonFile = global.getObject();

global.close(); 

<cfset var global = createObject("component", "lib.cfmumps.global")>
<cfset global.open("DD", [200])> 

<cfset var newPersonFile = global.getObject()>

<cfset global.close()> 

As you can see in the above code snippets, the global variable has been initialized to an instance of the Global API CFC, and opened with a reference to ^DD(200). The getObject() API was then used to populate the newPersonFile variable with a structure whose layout and members contain all the data from ^DD(200) and its descendants. You can now work with this information in-memory, without incurring the performance penalties of further accesses to fixed storage.