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.
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.
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.
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]
*[fdscript]
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.
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:
@/atut/0
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).
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:
(commit-pools)
That's it! You're now ready to proceed with the pool-get.c introductory tutorial.