Frequently Asked Questions
General questions
Building, modifying, and understanding RTA
General questions
What is RTA?
RTA is library that lets PostgreSQL clients talk to your daemon
using SQL and the PostgreSQL protocol. RTA is not a stand-alone
database server or file system but a library which offers
up your program's internal structures and arrays as database tables.
RTA uses a subset of the Postgres protocol but is still compatible
with the Postgres bindings for "C",
PHP, and the Postgres command line tool, psql.
What is the purpose of RTA?
It provides a means for external programs to view and edit the
tables in your running program. This makes debugging easier and
means that the user interface parts of your system can be kept
apart from the core functionality.
So, is this a database, or what?
No, it is *not* a database. It is an API which lets external
programs view and edit your internal data as if the data were in a
database.
Is this like the /proc filesystem?
Yes, in a way. The /proc system lets you view the kernel's internal
data as if the data were stored in files in a filesystem. RTA lets
you view your program's internal tables (arrays of structures) as
if they were tables in a PostgreSQL database.
Why PostgreSQL?
Mostly because both the design and the documentation of the
PostgreSQL protocol are very clean. PostgreSQL offers a simple,
well documented protocol to the client. (Our thanks to the designers
and tech-writers for PostgreSQL.)
What SQL commands are implemented?
Only four: SELECT, UPDATE, INSERT, and DELETE, and even then it is
only a subset of their PostgreSQL equivalents. See rta.h for the
syntax details of the commands. RTA does not implement transactions.
What SQL/Postgres commands are not
implemented?
This is not a database! RTA does not have the usual PosgreSQL meta
tables, nor does it have CREATE TABLE, ALTER TABLE, or DROP TABLE.
The command line tool for PostgreSQL, psql, will connect to a program
with RTA, but none of the psql backslash commands will work (since
most of the backslash commands require a real PostgreSQL database).
Why such a small subset of SQL?
This is not a database; it is an API. SELECT and UPDATE are the
minimum needed to read and edit the data in your running program.
Who should not use RTA?
RTA is great if you have data already arranged as structs or as
array of structs. It is a little more difficult to use if you have
lots of structs pointing to other structs pointing to other
structs. That is, it is a good fit for simple tables of data and is
not a good fit for a deeply nested tree structure of data.
RTA is also not a good fit for program that use a C style "union"
for what would be a column. RTA can not deal with columns of data
that can change data type while in use.
How big is it?
The stripped shared-object SQL interface library (librtadb.so.3)
is 56 KB and the static (.a) library is 50 KB.
Do I need to know SQL to use RTA?
Not really. Usually only two commands are required and they match
pretty well with the intuitive idea of "change this column in this
table where ...". It is pretty simple.
How difficult is it to learn and use RTA?
It is easy to learn. There are only two important data structures
(one to describe a table and one to describe a column) and only seven
subroutines in the API. The tutorial elsewhere on this page should
give you a pretty good idea of the simplicity of the approach.
It is simple but *may* require some effort on your part. Each table
and each column in each table needs to be defined in a data
structure. While simple, it can be a fair amount of work.
How do I report bugs?
Please select "Contact Info" from the menu above to open a
query form. Please give as much detail as possible.
Where can I get help?
Please select "Contact Info" from the menu above to open a
query form. Please give as much detail as possible.
Can I send you money?
Please send bug reports and change requests. Send money to the Free
Software Foundation.
Building, modifying, and understanding RTA
What do I need to do to use RTA in my
program?
You need to describe each table you wish to make available. A table
is an array of structures. Each member of the structure forms a
column of the table. The table description includes attributes of
the table in general and a description of each column in the table.
See the sample application and the API reference for more
detail.
What tools are available to explore RTA
tables?
RTA uses two internal tables (rta_tables and rta_columns) to
store information about all of the tables visible to RTA. RTA
include a "table editor" written in PHP that lets you use a web
browser to view and edit any table in your application. The RTA
table editor does not need prior knowledge about the tables since
it can read everything it need from the two meta tables. Follow
the "Live Demo" link to see the table editor in action.
What libraries, tools and include files are
needed?
We use the following system include files: libgen.h, limits.h,
stdarg.h, stddef.h, stdio.h, stdlib.h, string.h, syslog.h, and the
following system and utility calls: closelog(), dirname(),
fclose(), fdopen(), fgets(), fopen(), fprintf(), free(), malloc(),
memchr(), mkstemp(), offsetof(), openlog(), rename(), snprintf(),
sprintf(), sscanf(), strcat(), strcmp(), strcpy(), strlen(),
strncmp(), strncpy(), strstr(), syslog(), va_arg(), va_end(),
va_start(). You will need yacc (bison) and lex (flex) to build RTA.
Do I need the Postgres libraries?
Your application does not need any libraries or include files from
the PostgreSQL distribution. Your *client* applications may need
PostgreSQL libraries as appropriate.
Can I link to it statically?
Yes, You can link to the .a file or just include the .c files in
the build of your application.
What has it been tested on?
It has been used successfully Red Hat, SUSE, and Ubuntu system.
With slight modification it can be used on Macintosh and Windows
systems as well.
Can I add my own data type?
Yes. You will need to modify the lex program to recognize the new
data type as well as the .c files which print or compare its
values.
Why are there "magic" numbers in the
code?
Several places in the code contain what seem like magic values.
These are all related to the PostgreSQL protocol and should all be
described by comments in the surrounding code.
Why are the pseudo-tables arrays of
pointers?
The short answer is to save memory. If rta_add_table() were to copy
the table definition your application would have the definition two
places in memory: internal to RTA, and in your application code. By
saving the pointers to the table and column definitions we avoid
using lots of memory to duplicate data. Saving pointers has the
second advantage of letting you change the table definition on the
fly if needed.
Why do I get segmentation violations?
We've tried very hard to eliminate memory leaks and segmentation
violations from the RTA package but some might have slipped
through. A common source of problems is overrunning a string. Be
sure to verify that your strings have the proper size specified in
the column definitions.
How can I change the size of a table?
Allocate enough memory to store the new, larger table. Copy the old
table into the new space. Initialize the new rows added. Copy the
address of the new table into the "address" field of the table
definition and update the "nrows" field with the new number of
rows.
Why use native data type instead of INT4
and INT8?
The idea is to give easy access to *your* data structures. Since
most programmers use the native int, long long, and float, we do
too.
Why do I get "error while loading shared libraries:
librtadb.so.3"?
You need to put the librtadb.so files into one of
the system library directories or you need to something like "export
LD_LIBRARY_PATH=../src" in order to let the application find the
library.
How big should I make the output buffer for
rta_dbcommand()?
It depends on the number of rows and the size and number of fields
you request. You should be able to estimate the number of
characters in your response. Assume that strings are returned with
all bytes filled, that integers return 12 characters per field,
longs return 24, and floats return 24. Thus if you request two
integers, a 40 byte string and a float, you would need about
40+(2*12)+24=88 bytes. The Postgres overhead per row returned is
about 4 bytes. Make the output buffer for rta_dbcommand() big enough to
hold the maximum number of rows you want times the size of each
row. Be sure to use LIMIT and OFFSET to step through a big list of
returned rows.
Can I export a simple variable?
Sure. Just define a single column for your variable and a table
with a single row. You can make visible simple variables, single
structures, or arrays of structures.
Is RTA thread safe?
RTA is not currently thread safe. Please contact the authors
if this is very high on your wish list.
What is in the To-Do list?
Please let the authors know what features you would like added
or removed from Run Time Access. No additional changes are
anticipated at this time, but the list of possible changes
includes:
- UTF-8 support
- printf format string in the column definition
- ability to register more than one trigger per column
- secure login maintaining Postgres compatibility
- IPC and support for shared tables in shared memory
- specify pre or post for the write callback
- table save callback (to save file to flash?)
- execution times for table access, update
- count(*) function
- model output buffer mgmt on zlib to allow output streams
- add a column data type of "table" to allow nested tables
- make it thread safe
| 
Run Time Access
