FirstBase: FB_CLNT

URL: http://www.firstbasesoftware.com/man/man3/fb_clnt_create.htm
Last modified: 12 September 1995
Copyright © by FirstBase Software.
[ Index of Contents] [ FirstBase RDBMS Overview]

NAME

access, access_clnt, addidx_clnt, addrec_clnt, b_addrec_clnt, b_delrec_clnt, bulkrec_begin, bulkrec_end, chdir, chdir_clnt, clnt_create, clnt_destroy, clnt_timeout, close, close_clnt, closedb_clnt, closeidx_clnt, creat, creat_clnt, delrec_clnt, errno, errno_clnt, fetch_clnt, fetchrec, fetchrec_clnt, fetchxrec, fetchxrec_clnt, firstxrec_clnt, getwd_clnt, getctime, getctime_clnt, gethead_clnt, getrec_clnt, getirec_clnt, getxrec_clnt, lastxrec_clnt, lock_clnt, lockf, lockf_clnt, lseek, lseek_clnt, mkdir, mkdir_clnt, nextxrec_clnt, open, open_clnt, opendb_clnt, openidx_clnt, put_autoindex_clnt, putrec_clnt, read, read_clnt, rmdir, rmdir_clnt, s_lock_clnt, s_unlock_clnt, set_autoindex_clnt, status_clnt, store_clnt, subidx_clnt, symlink, symlink_clnt, sync_clnt, system_clnt, umask, umask_clnt, unlink, unlink_clnt, unlock_clnt, write, write_clnt - client/server mechanisms to communicate with fbserver

DESCRIPTION

FirstBase client routines allow C programs to communicate with fbserver and manipulate FirstBase databases. First, the client uses fb_clnt_create to generate a temporary server and establish a client/server link between the two processes. Then, additional calls to FirstBase client routines will send RPC requests to the server and wait for the server to reply. Finally, the client should issue the fb_clnt_destroy call to destroy the temporary server.

For the most part, these FirstBase client routines are designed to behave like their non-client counterparts. In these cases, the arguments to both will be the same. Additionally, many of these routines are called transparently from the standard non-client interface when cdb_use_rpc is set to one. For example, fb_addrec will really call fb_addrec_clnt when cdb_use_rpc is set. For more details, see setup(5), and the section on ADDITIONAL INTERFACES at the end of this manual page.

fb_access_clnt(path, mode)
char *path;
int mode;

This routine implements the standard Unix access(2) mechanism on the server.

fb_addidx_clnt(iname, db)
char *iname;
fb_database *db;

This routine emulates the standard FirstBase fb_addidx mechanism (see useidx(3)). On the server side, the Btree+ index iname is opened and added to the array of autoindexes, db->b_autoindex. Return status is either FB_AOK or FB_ERROR.

fb_addrec_clnt(db)
fb_database *db;

Adds the record stored in the database structure on the server side and updates all autoindexes. fb_addrec_clnt returns FB_ERROR if any part of the request failed, or FB_AOK if the server request was completed.

fb_b_addrec_clnt(db)
fb_database *db;

Batch mechanism for adding many records at once. See the discussion in fb_addrec(3). Adds the record stored in the database structure on the server side and updates all autoindexes. fb_b_addrec_clnt returns FB_ERROR if any part of the request failed, or FB_AOK if the server request was completed.

fb_bulkrec_begin_clnt(db, fwait)
fb_database *db;
int fwait;

Used to begin bulk record processing. See the discussion in bulkrec(3). Returns FB_AOK or FB_ERROR, and might set cdb_error.

fb_bulkrec_end_clnt(db)
fb_database *db;

Used to begin bulk record processing. See the discussion in bulkrec(3). Returns FB_AOK or FB_ERROR.

fb_chdir_clnt(path)
char *path;

This routine implements the standard Unix chdir(2) mechanism on the server.

fb_clnt_timeout(seconds)
int seconds;

Controls the number of seconds a FirstBase RPC client/server request will wait before a timeout occurs. The default is cdb_locktime + 10. There is not a return status.

fb_close_clnt(fd)
int fd;

Closes the file descriptor on the server. Similar to close(2). Return status is 0 on success or -1 on failure.

fb_closedb_clnt(db)
fb_database *db;

Closes the database on the server and frees up the storage on the client. Return status is either FB_AOK or FB_ERROR.

fb_closeidx_clnt(db)
fb_database *db;

Emulates the standard FirstBase fb_closeidx mechanism (see openidx(3)). Closes the current index in database db. Returns FB_AOK or FB_ERROR.

fb_creat_clnt(name, mode)
char *name;
int mode;

Create the file name with mode on the server. Similar to creat(2). Return status is -1 on failure or the non-negative file descriptor on completion.

fb_delrec_clnt(db)
fb_database *db;

Flags the current db record as being deleted. In addition, deletes the entry from all auto indexes. Return status is either FB_AOK or FB_ERROR.

fb_b_delrec_clnt(db)
fb_database *db;

Batch mechanism for deleting many records at once. See the discussion in fb_delrec(3). Deletes the record stored in the database structure on the server side and updates all autoindexes. fb_b_delrec_clnt returns FB_ERROR if any part of the request failed, or FB_AOK if the server request was completed.

fb_fetch_clnt(f, s, db)
fb_field *f;
char *s;
fb_database *db;

Fetches the server data for the field f from database db. This data is copied into the buffer s. Return status is either FB_AOK or FB_ERROR.

fb_fetchrec_clnt(rec, db)
long rec;
fb_database *db;

This routine is a combination of fb_getrec_clnt and a series fb_fetch_clnt requests, but is done all in one RPC call. fb_fetchrec_clnt does a getrec of record rec for database db on the server. The server returns the contents of all fields and the client stores them so that simple fetch calls or use of the FLD macro from the client process can access each field individually. Return status is either FB_AOK or FB_ERROR.
The benefits of fb_fetchrec_clnt are that only one RPC call is done. However, the entire record is shipped to the client, which might be inefficient depending on the application.

fb_fetchxrec_clnt(key, db)
char *key;
fb_database *db;

Fb_fetchxrec_clnt does an fb_getxrec_clnt and a series of fb_fetch_clnt requests, but in a single RPC call. See fb_fetchrec_clnt for more comments. Return status is either FB_AOK or FB_ERROR.

fb_firstxrec_clnt(db)
fb_database *db;

Locate and load (getrec) the first indexed record of the database db on the server. Return status is either FB_AOK or FB_ERROR.

fb_free_globals_clnt()

Executes an fb_free_globals(3) on both the server and the client side. There is no return status.

time_t fb_getctime_clnt(path)
char *path;

This routine returns the time_t value of the file path as described by the standard Unix stat(2) command.

fb_gethead_clnt(db)
fb_database *db;

Get the header information from the server about database db. The information is stored in the client database structure, into db->reccnt and db->delcnt. Return status is either FB_AOK or FB_ERROR.

fb_getrec_clnt(rec, db)
long rec;
fb_database *db;

Fb_getrec_clnt loads record rec from database db on the server. Fields of the loaded record are then available via fb_fetch_clnt. In addition, see fb_fetchrec_clnt. Return status is either FB_AOK or FB_ERROR.

fb_getirec_clnt(rec, db)
long rec;
fb_database *db;

Fb_getirec_clnt loads record rec from database db on the server and synchronizes the current btree index with the loaded record. Return status is either FB_AOK or FB_ERROR.

fb_getwd_clnt(buf)
char *buf;

This routine returns the current working directory in the buffer buf.

fb_getxrec_clnt(key, db)
char *key;
fb_database *db;

Fb_getxrec_clnt searches the current index of the server database db and loads the first record with an index value of key. Fields of the loaded record are then available via fb_fetch_clnt. In addition, see fb_fetchxrec_clnt. Return status is either FB_AOK or FB_ERROR.

fb_lastxrec_clnt(db)
fb_database *db;

Locate and load (getrec) the last indexed record of the database db on the server. Return status is either FB_AOK or FB_ERROR.

fb_lock_clnt(rec, db, wait)
long rec;
fb_database *db;
int wait;

Fb_lock_clnt is analogous to the FirstBase call fb_lock(3). This mechanism locks the record rec of database db on the server. If wait is WAIT (1), the process will block until the lock is granted, or a timeout occurs. See fb_lock(3) for more details. Return status is either FB_AOK or FB_ERROR.

fb_lockf_clnt(fd, cmd, size)
int fd, cmd;
long size;

This routine implements the standard Unix lockf(3) mechanism.

fb_lseek_clnt(des, offset, whence)
int des, whence;
off_t offset;

This routine implements the standard Unix lseek(2) mechanism.

fb_mkdir_clnt(path, mode)
char *path;
int mode;

This routine implements the standard Unix mkdir(2) mechanism.

fb_nextxrec_clnt(db)
fb_database *db;

Load (getrec) the last next indexed record of the database db on the server. Return status is either FB_AOK or FB_ERROR.

fb_open_clnt(path, flags)
char *path;
int flags;

Opens the file on the server side using the standard open(2) library call. The path, flags and return value are all the same as the UNIX call.

fb_opendb_clnt(db, mode, ixflag, ixoption)
fb_database *db;
int mode;
int ixflag;
int ixoption;

This routine emulates the standard FirstBase opendb(3) mechanism. On the server side, the database is opened, using mode, ixflag and ixoption. Field names and database information are returned to the client and loaded into the database db. Additionally, all expected space allocations are done (like db->arec, etc). Return status is either FB_AOK or FB_ERROR.

fb_openidx_clnt(iname, db)
char *iname;
fb_database *db;

This routine emulates the standard FirstBase openidx(3) mechanism. On the server side, the index iname is opened and associated as the current index for database db. Return status is either FB_AOK or FB_ERROR.

fb_put_autoindex_clnt(db)
fb_database *db;

Updates any autoindexes reflected by the current record. See put_autoindex(3) for more details. Return status is either FB_AOK or FB_ERROR.

fb_putrec_clnt(rec, db)
long rec;
fb_database *db;

Fb_putrec_clnt stores the current record as logical record rec into the database db on the server. Return status is either FB_AOK or FB_ERROR.

fb_read_clnt(d, buf, nbytes)
int d;
char *buf;
int nbytes;

Implements the standard read(2) call on the server side.

fb_rmdir_clnt(path)
char *path;

This routine implements the standard Unix rmdir(2) mechanism.

fb_s_lock_clnt(fd, fwait, fname)
int fd;
int fwait;
char *fname;

Locks the file descriptor on the server side. See fb_lock(3) for more details. Return status is either FB_AOK or FB_ERROR.

fb_s_unlock_clnt(fd, fname)
int fd;
char *fname;

Unlocks the file descriptor on the server side. See fb_lock(3) for more details. Return status is either FB_AOK or FB_ERROR.

fb_set_autoindex_clnt(db)
fb_database *db;

Stores all index values in case indexes need updating. See put_autoindex(3) for more details. Return status is either FB_AOK or FB_ERROR.

fb_status_clnt(db, output)
fb_database *db;
char *output;

Returns textual information about each of the open server databases. This text is stored into output. The information returned is simplistic: database name, index name, as well as record and delete counts. Return status is either FB_AOK or FB_ERROR.

fb_store_clnt(k, s, db)
fb_field *k;
char *s;
fb_database *db;

Store places string s into field k of the database db on the server. See store(3) for more detail about field storage. Return status is either FB_AOK or FB_ERROR.

fb_subidx_clnt(iname, db)
char *iname;
fb_database *db;

This routine emulates the standard FirstBase fb_subidx mechanism (see useidx(3)). On the server side, the Btree+ index iname is closed and removed from the array of autoindexes, db->b_autoindex. Return status is either FB_AOK or FB_ERROR.

fb_symlink_clnt(name1, name2)
char *name1, *name2

This routine implements the standard Unix symlink(2) mechanism.

fb_system_clnt(s, rootperm)
char *s;
int rootperm;

This routine emulates the standard FirstBase fb_system mechanism (see fb_system(3)), submitting the string s to the shell on the server side. Return status is the exit status of the shell execution.

fb_sync_clnt(db)
fb_database *db;

Synchronize the database and all data files on the server side. This is similar to the fb_sync(3) call.

fb_umask_clnt(numask)
int numask

This routine implements the Unix umask(2) call.

fb_unlink_clnt(path)
char *path;

This routine implements the Unix unlink(2) call.

fb_unlock_clnt(rec, db)
long rec;
fb_database *db;

Fb_unlock_clnt is analogous to the FirstBase call cdb_unlock(3). This mechanism unlocks the record rec of database db on the server. See fb_lock(3) for more details. Return status is either FB_AOK or FB_ERROR.

fb_useidx_clnt(n, db)
int n;
fb_database *db;

This routine emulates the standard FirstBase fb_useidx mechanism (see useidx(3)). On the server side, the Btree+ index iname is marked as the current index. Return status is either FB_AOK or FB_ERROR.

fb_write_clnt(d, buf, nbytes)
int d;
char *buf;
int nbytes;

Implements the standard write(2) call on the server side.

ADDITIONAL INTERFACES

Some of the calls built into the FirstBase client library do not have explicit FirstBase non-rpc counterparts. However, some have UNIX counterparts. For all of these, the FirstBase client library provides an additional set of routines that will behave transparently during RPC and non-RPC programs, like other FirstBase mechanisms.

The following routines will call the proper equivalent function running as a standalone process (non-RPC) or when used with FirstBase client/server RPC calls. In all cases the parameters are the same as the ones listed above.

      fb_chdir
      fb_close
      fb_creat
      fb_errno
      fb_fetchrec
      fb_fetchxrec
      fb_getctime
      fb_getwd
      fb_lockf
      fb_lseek
      fb_open
      fb_read
      fb_rmdir
      fb_symlink
      fb_umask
      fb_unlink
      fb_write

Note that fb_fetchrec under non-RPC will use getrec(3), and fb_fetchxrec will use getxrec(3).

NAME

DESCRIPTION

ADDITIONAL INTERFACES

SEE ALSO