4.17 C/Base Catalog Functions



RMS includes functions to access information from the C/Base catalog. The C/Base catalog is a system wide database containing information on all databases, logical RMSfiles, logical formfiles, and logical reportfiles stored on the system. There are functions to read catalog information, and functions for dealing with logical names and pathnames.

Two functions return information about a database. The first, dbfind(C-3), returns information about a database by its name. Dbfind searches the C/Base catalog for the named database and, if found, returns a pointer to a structure that describes the database. The structure is defined in the include file <cbase/dbase.h>. A NULL pointer is returned if the database name is not found. A sample call to dbfind looks like:

DB *dp;

dp = dbfind ("demo");

if (dp == NULL)

puts ("Demo database not defined");

If the pointer passed to dbfind is a NULL pointer, or points to an empty string, the default database name is used.

The second function for finding database information, dbfindn(C-3), is passed a number to specify which database to find. Database numbers start at 1. The actual order of the databases matches the order they are recorded in the catalog (which is somewhat random). This function is used to scan through all database entries. The following example illustrates dbfindn by printing the names and home directories of all databases:

DB *dp;

int i;

i = 1;

while (dp = dbfindn (i++) {

printf ("%32s %s\n", dp->db_dbname,

dp->db_home);

}

Logical RMSfiles have a set of searching functions similar to the database set. However, for logical RMSfiles, the database name must be specified. The first function finds a particular logical RMSfile by logical name. This function, dlfind(C-3), is passed two arguments: the database name and the logical name. The following example shows a sample call to dlfind:

LF *lf;

lf = dlfind ("demo", "mag");

if (lf == NULL)

puts ("No magazine file defined for Demo");

Like dbfind, the database name can be a NULL pointer or an empty string. In this case, the default database is used.

The other logical RMSfile function, dlfindn(C-3), retrieves information about RMSfiles in one database by number. This function is passed the database name and a file number. File numbers start at 1. Only logical RMSfiles contained in the named database are returned. The following code illustrates dlfindn by listing the logical RMSfile name and pathname of each logical RMSfile in the database demo:

LF *lf;

int i;

i = 1;

while (lf = dlfindn ("demo", i++)) {

printf ("%32s %s\n", lf->lf_lname,

lf->lf_sname);

}

Up to now, the database functions have been returning information about databases and logical RMSfiles. The next set of functions deal with logical RMSfile names. Dbpath(C-3) returns the pathname of a logical RMSfile name. Logical RMSfile names can be logical file names or a pathname. The following example illustrates how to call dbpath:

char *name = "demo~mag"

printf ("System name for %s is %s\n",

name, dbpath (name));

If the argument passed to dbpath is not a valid logical name, the argument is returned as is. The pathname returned for logical RMSfile names is the absolute pathname of the RMS data file. This is not just the system name stored in the RMSfile catalog. Instead, if necessary, the home directory of the database is prepended to the system name.

The next function breaks up a logical name into its database name and logical file name components. Dbparse(C-3) is passed a logical name and pointers to two character pointers. If the logical name is a valid logical file name, the first character pointer is changed to point to the database name and the second pointer is changed to point to the logical file name. WARNING: if the database name is not specified in the logical name, the database name pointer points to static data that is overwritten frequently. You should save the database name before calling any other RMS function. The following code illustrates how to call dbparse:

char dbname[DBNAMZ];

char line[200];

char *dbp, *lfp;

puts ("Enter a logical name:");

while (gets (line)) {

if (dbparse (line, &dbp, &lfp) < 0)

puts ("That is not a valid name.");

else {

strncpy (dbname, dbp, DBNAMZ);

printf ("Database name is %s,", dbname);

printf ("Logical file name is %s.\n", lfp);

}

puts ("Enter a logical name:");

}

DBNAMZ is the maximum length of a database name. It is defined in the include file <cbase/dbase.h>.

The last of the database functions establishes a default database and forces the associated log file to be opened. Dbopen(C-3) is passed the name of a database to "open". If the argument passed is NULL or an empty string, the value of the environment variable DBASE is used as the name of the database. The following code illustrates how to call dbopen:

if (dbopen ("demo")) {

/* open failed, show why */

puts (derrmsg());

}

This function can also change the default database after a program has started executing. The only restriction on this is that the log file of the current default database match the log file of the new database.