FramerD C API Tutorials Test Server Setup

This document takes you step-by-step through building the FramerD pools and data you'll use in the programming tutorials. The document is divided up into pre-tutorial setup (that you'll need to do before you begin the tutorial), and steps to be performed in preparation for each tutorial step. Thus, you will continually refer to this document throughout the tutorial.

Though the tutorial itself focuses on programming FramerD through the C API, you'll use FDScript and the command-line tools included with FramerD extensively in these setup steps.

Pre-Tutorial Setup

Creating the File Pool

The very first thing you have to do is create an initial pool with some very simple data that you'll access through the FramerD C API. Use the make-file-pool tool to do this:

make-file-pool tutorial.pool 32768

This creates a file in the current directory called tutorial.pool, which contains a FramerD pool with a capacity of 32768 OIDs. Note that the capacity specified must be a power of two. If it is not, FramerD will automatically round it up to the next power of two.

Serving the File Pool Over the Network

Now that you've created the file pool, you have to run fdserver against it so that it's shared and available to network clients. The simplest way to accomplish this is by invoking fdserver with the server name and the pool name, but it doesn't work (see below). Here's the command as it should be, but don't bother typing it in:

fdserver atut --pool tutorial.pool

This shares the pool contained in the file tutorial.pool as server atut@host, where host is the hostname of your machine. Note that, unless overridden, this will share on port 2888, which is derived from atut using touch-tone encoding. If you wish to use a different port, specify it in place of the string atut on the fdserver command line. You may either specify another string to be touch-tone encoded, or a number to be taken literally. Note that if you specify a number, you will need to refer to that server as port@host instead of name@host, since there is no server "name" per se (server "names" are simply used to generate port numbers internally, and have no real meaning).

However, as mentioned above, this doesn't seem to work as expected. There seems to be a subtle bug in fdserver that causes it to seg fault if you invoke the server without a configuration file, on a port that's different than the one implied by the base filename of the pool file. Thus, fdserver fred --pool fred.pool would work, but fdserver frood --pool fred.pool wouldn't. I'm not up to patching the sources right now, but I have a workaround for you, which is necessary if you wish to use the names as I've used them in the tutorials:

First, create an initialization file for fdserver called atut.fdx, that contains the following:

(serve-pool "tutorial.pool")

Now, invoke fdserver with this command line:

fdserver atut

What happens here is that fdserver looks for the file atut.fdx before it does anything else. Finding that file, it executes the 'initialization' commands contained therein. The only command ((serve-pool "tutorial.pool")) tells fdserver to serve the pool file tutorial.pool, and nothing else. fdserver takes its port number from the string "atut", specified on the command line. The end result is what we intended with the original command line.

pool-get.c Tutorial Setup

Connecting to the Pool Server

In preparation for pool-get.c, you'll need to add an OID to your pool, and give it some data. Invoke fdscript with no arguments, and you should see the banner and prompt:

[02:08:24 MIT FramerD library 1.0 (c) 1994-1999, built Jun  6 1999]

Now, connect to the tutorial pool using the use-pool command:

*[fdscript] (use-pool "atut@host")

host is your hostname, and atut should reflect whatever value you used as the server/port name when starting fdserver above.

The output of this command will be a session information banner, along with some miscellaneous status, similar to this:

[02:47:50 Session id=fdscript tlilley@defiant /PID:1932 /OS:i686-unknown-linux /Compiled:Jun  6 1999 /Started:Mon Jun  7 02:47:50 1999]
[02:47:50 Added pool atut@defiant]
[#POOL atut@defiant @375ae87e/20020+32768 {}]

The #POOL status line reports the super-pool half of the OID (375ae87e), the base offset within the super-pool of this pool (20020), and the capacity of the pool (32768). Pay attention to these numbers, as we'll need them later in the tutorial.

Allocating an OID

Now you'll need to allocate an OID from the pool to which you're connected. In the fdscript listener, enter:

(allocate-oid "atut@host")

fdscript will return a response line that simply contains the new OID, like so:


Note that this expression is a logical OID. You can tell this by the forward-slash immediately following the initial at ('@') sign. By simply adding the super-pool OID, the base offset of this pool, and the logical part of this OID, we can compute the literal OID. For this example, based on our #POOL output discussed above, the literal OID is @375ae87e/20020. For more details on literal and logical OIDs, and conversions between them, see The Object Database. Not also that, in properly written FramerD programs, you can use literal and logical OIDs interchangably (see the note in pool-get.c for an explanation of what "properly written" means, and why it matters).

Assigning a Value to an OID

Now that you've created an OID, you need to assign a simple string value to it for our testing:

(set-oid-value! @/atut/0 "simple value")

The fdserver listener will report ;; No return value expected, since the value set function doesn't return anything. To double-check that the value was set as you expected, enter this command at the listener prompt:

(oid-value @/atut/0)

The system should report "simple value", as we expect. Finally, commit the changes to the pool (even though fdserver will commit if it exits normally) with this command:


That's it! You're now ready to proceed with the pool-get.c introductory tutorial.

Tripp Lilley
Last modified: Mon Jun 7 16:43:32 EDT 1999