We describe BRL data structures as abstract data types. That is we specify only the operations the data structures support.
The ADT BINARY OBJECT implements an abstract "binary object in memory" type. BINARY OBJECT is accessed via the following operations:
BOB *brObjAlloc(int size);
Constructs a binary object with the given size. On successful completion, brObjAlloc returns a pointer to the newly created object. In the event of error, it returns null.
BOB *brObjCopy(BOB *source);
Copy constructor. Constructs a binary object from the given source object. On successful completion, brObjCopy returns a pointer to the newly created object. In the event of error, it returns null.
void brObjFree(BOB *obj);
Removes the object from the memory.
char *brObjData(BOB *obj);
Returns a pointer to this object.
int brObjSize(BOB *obj);
Returns the object size.Read functions are used to read data from the given object:
BR_LONG brObjReadLong(BOB *obj);
Read a long word (4 bytes).
float brObjReadFloat(BOB *obj);
Read a float (4 bytes).
double brObjReadDouble(BOB *obj);
Read a double (8 bytes).
BR_SHORT brObjReadShort(BOB *obj);
Read a two byte word.
char brObjReadChar(BOB *obj);
Read a single byte character.
char *brObjReadString(BOB *obj);
Read a null terminated string. String is limited to 256 chars including null terminator.
BOID brObjReadOid4(BOB *obj);
Read an object identity. Assumes Oid4 is 4 bytes.Write functions are used to write data to the given object:
void brObjWriteLong(BOB *obj, BR_LONG data);
Write a long word (4 bytes).
void brObjWriteFloat(BOB *obj, float data);
Write a float (4 bytes).
void brObjWriteDouble(BOB *obj, double data);
Write a double (8 bytes).
void brObjWriteShort(BOB *obj, BR_SHORT data);
Write a two byte word.
void brObjWriteChar(BOB *obj, char data);
Write a single byte character.
void brObjWriteString(BOB *obj, char *string);
Write a null terminated string. String is limited to 256 chars including null terminator.
void brObjWriteBOID(BOB *obj, Oid4 id);
Write an object identity. Assumes Oid4 is 4 bytes.
The ADT BINARY RELATION provides a simple mechanism for associating two BINARY OBJECT types, known as the value and the key, in one BINARY RELATION type. BINARY RELATION is accessed via the following operations:
Open/Close functions:
BR *brOpen(char *relation_name);
Opens a binary relation with the given name. On successful completion, brOpen returns a pointer to the open relation. In the event of error, it returns null. You can simultaneously open up to 40 relations.
int brClose(BR *rel);
Closes the relation. On successful completion, brClose returns 1. In the event of error it returns 0.Update functions:
int brAdd(BR *rel, BOB *key, BOB *value );
Adds the given pair of key and value to the relation only if it is not already a member. If it is found in the relation brAdd does nothing. On successful completion, brAdd returns 1. In the event of error it returns 0.
int brDestroy(BR *rel);
Removes the current pair of brKey(rel) and brValue(rel) from the relation. If the relation is empty, brDestroy does nothing. On successful completion, brDestroy returns 1. In the event of error it returns 0.
int brDestroyAll(BR *rel);
Removes all pairs from the relation. If the relation is empty, brDestroyAll does nothing. On successful completion, brDestroyAll returns 1. In the event of error it returns 0.
int brUpdate(BR *rel, BOB *value);
Updates the current pair with the value. On successful completion, brUpdate returns 1. In the event of error it returns 0.Iterate functions:
int brFirst(BR *rel);
Moves the current position to the first stored pair. On successful completion, brFirst returns 1. In the event of error it returns 0.
int brLast(BR *rel);
Moves the current position to the last stored pair. On successful completion, brLast returns 1. In the event of error it returns 0.
int brNext(BR *rel);
Moves the current position to the next stored pair. On successful completion, brNext returns 1. In the event of error it returns 0.
int brPrev(BR *rel);
Moves the current position to the previos stored pair. On successful completion, brPrev returns 1. In the event of error it returns 0.
BOB *brKey(BR *rel);
Returns a pointer to the key object of the current pair. If there is an error or if the relation is empty it returns 0.
BOB *brKeyObj(BR *rel);
Returns a pointer to the key object of the current pair of the relation.
BOB *brValue(BR *rel);
Returns a pointer to the value object of the current pair. If there is an error or if the relation is empty it returns 0.
BOB *brValueObj(BR *rel);
Returns a pointer to the value object of the current pair of the relation.Evaluate functions:
BOB *brEval(BR *rel, BOB *key);
Evaluates the value in the relation by the supplied key. Returns a pointer to the value object in the relation that has a given key. Null is returned if no pair meets the condition. In the event of error it returns 0.
BOB *brEvalFirst(BR *rel, BOB *key);
Evaluates the first value in the relation by the supplied key. Returns a pointer to the first value object in the relation that has a given key. Null is returned if no pair meets the condition. In the event of error it returns 0.
BOB *brEvalLast(BR *rel, BOB *key);
Evaluates the last value in the relation by the supplied key. Returns a pointer to the last value object in the relation that has a given key. Null is returned if no pair meets the condition. In the event of error it returns 0.Test function:
int brTest(BR *rel, BOB *key, BOB *value);
Returns 1 if the relation contains the given pair; otherwise it returns 0.
int brCard(BR *rel);
Returns the relation cardinality: UNIQUE or MULTIPLE.
unsigned long brCount(BR *rel);
Returns the number of pairs in the relation.
The ADT DATABASE is a collection of binary relations. DATABASE is accessed via the following operations:
Open/close functions:
int brDBCreate(char *database_name,int num);
Constructs and "zeroes" a database (and associated file) with the given name and maximum number of relations. On successful completion, brDBCreate returns 1; otherwise it returns 0.
int brDBOpen(char *database_name);
Opens a database (and associated file) with the given name. On successful completion, brDBOpen returns 1; ottherwise it returns 0.
int brDBClose(void);
Closes the database (and associated file). On successful completion, brDBClose returns 1. In the event of error it returns 0.Update functions:
BR *brDBAdd(char *relation_name,int keysz, int valuesz, int crd);
Adds a new relation to the database only if it is not already a member. On successful completion, brDBAdd returns a pointer to the newly created relation. In the event of error, it returns null.Parameters:
name name of relation keysz size of key object valuesz size of value object crd relation cardinality is one of enumeration: enum { UNIQUE = 0, MULTIPLE = 1 };You can not create a relation with the sum of keysz and valuesz more than 336 bytes.
int brDBDestroy(char *relation_name);
Removes the given relation from the databases. If the relation is not found or the database is empty, brDBDestroy does nothing. On successful completion, brDBDestroy returns 1. In the event of error it returns 0.Access functions:
char *brDBFirst(void);
Returns the name of the first relation in the database. In the event of error it returns 0.
char *brDBNext(void);
Returns the name of the next relation in the database. In the event of error it returns 0.
int brDBTest(char *relation_name);
Returns 1 if the relation is in the database; otherwise it returns 0.
int brDBMax(void);
Returns the maximum number of relations in the database.
int brDBCount(void);
Returns the current number of relations in the database.
void brDBClear(void);
Clears the database state.
int brDBState(void);
Returns the database state. If an error occurs when a BR library function called, an internal state of the database is set. You retrieve the error code for the last operation that reported an error by calling brDBState. It returns the database state from the enumeration:BR_OK = 0, /* No error */ BR_FAIL = -1, /* Last operation failed */ BR_TOOMANYOPENBR = -2, /* Too many open relations */ BR_NOENTRY = -3, /* No such relation */ BR_READFAIL = -4, /* Read error */ BR_WRITEFAIL = -5, /* Write error */ BR_INVARG = -6, /* Invalid argument */ BR_OFFSET = -7 /* Invalid offset */