The CFC Object Model

The CFML programming language provides object-oriented programming facilities by way of CF Components, commonly referred to as CFCs. Each CFC is conceptually similar to a class in other OO languages, which means that a CFC encapsulates both data and code. Data members of CFCs are referred to as properties, while the code to interact with those properties are methods. All CFC methods are actually functions (similar to extrinsic functions in MUMPS) which gain the benefits of the properties exposed in their containing CFC. In the case of CFMumps, each API is a CFC whose properties define and maintain the state of the MUMPS database connection, and whose methods are the APIs against which your applications will be developed, such as get(), set(), kill(), data(), and order().

You can think of each CFC as a complex, high-level data type that just happens to also contain code that you can run.

In order to gain access to the methods and properties of the CFCs which implement the CFMumps API, you need to create an instance of the appropriate CFC. An instance is simply a variable through which you access the methods and properties of the API you wish to use. Creating an instance is accomplished with the createObject() CFML/CFScript function.

Here is an example–expressed in both CFScript and tag-based CFML--creating an instance of the basic API:

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

<cfset var myCFCInstance = createObject("component", "lib.cfmumps.mumps")>

Each of the above code snippets will produce identical results: the variable myCFCInstance is created and initialized as an instance of lib.cfmumps.mumps, which is the component that implements the CFMumps basic API. Its methods are available by appending a dot to the variable name myCFCInstance, followed by the name of the method you wish to call, as follows:

myCFCInstance.open();

<cfset myCFCInstance.open()>

The above examples open the database for the myCFCInstance instance of the lib.cfmumps.mumps CFC.

Connecting to MUMPS

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 prefer, 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/IP 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(); 

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.