Let's see how to make use
of database tables.
First off, be warned that JRXDbase is not
a visual bean, since it doesn't need to be displayed. The
bean provides database access capabilities to a Java
program, that must then provide visualization of the
data.
Use in IBM VisualAge for Java:
Adding a Bean into the Visual Composition Editor (the
white space where you assemble beans and code) is quite
easy: just select the Bean category where you stored the
Beans, and the following new icon will appear there:

Select it and then click where you want
it to be placed. You can connect JRXDBase features to
other beans events and properties, just like you would do
with any other bean.
Use in Symantec Visual Café:
Since this isn't a visual bean, you should treat it like
a normal class -- use this page to get acquainted with
the available methods.
Use of the JRXDBase class with plain Jdk:
import nrio.JRXDbase;
Is required in your Java source file.
The default return strings for the
following methods are:
DBNOTSTARTED: (can't work on
nothing)
READY: (no errors)
SYNTAX ERROR: (go figure)
ERROR:FILE ACCESS PROBLEMS
(something weird at file level)
Unless stated otherwise. More error codes will be
introduced as
the RXDbase will be enhanced.
Index of available constructors and
methods:
JRXDbase()
- A simple constructor.
JRXDbase(String
sName, String[][] sRec)
- A constructor used to create a database.
JRXDbase(String
sName)
- A constructor used to connect to an existing
database.
String
addfield(String sFieldName, String sFieldLength,
String sFieldIndexingMethod)
- Adds a field to the currently opened database.
String
connect(String sName, String[][] sRec)
- Creates a new database and connects to it.
String connect( sName)
- Connects to an existing database.
String
definefilter(String sFilter)
- Defines a filter to be used in future loadrec
calls.
String
delerec(String[] sToDele, boolean bDelete)
- Deletes/Undeletes one or more records.
String
deletedb(String sDbName)
- Deletes a whole database.
String
delfield(String sFieldName)
- Deletes a field of the currently opened database.
String disconnect()
- Disconnects from the currently opened database.
String[][]
getdbinfo()
- Gets information about record structure for the
currently opened database.
String[] getdbstats()
- Gets some useful statistics about the database.
String[] getdbstatus()
- Returns the current in use filter and release
version for RXDbase.
String
globalrebuildidx()
- Rebuilds all of the indexes.
String[][]
loadrec(String sIdx, String sHowManyRec, String
sStart, boolean bForward)
- Loads a set of records.
String[][]
loadrecwithfilter(String sIdx, String
sHowManyRec, String sStart, boolean bForward,
String sFilter)
- Loads a set of records according to a temporary
filter.
String modfieldidx(String
sFieldName, String sFieldIndexingMethod)
- Modifies (on the fly) indexing strategy for a
field.
String
modfieldlength(String sFieldName, String
sNewLength)
- Modifies (on the fly) the length of a field.
String
modfieldname(String sOldName, String sNewName)
- Modifies (on the fly) the name of a field.
String
modirec(String[][] sToModi)
- Modifies one or more records.
String
pack()
- Packs the database (physically purge deleted
records).
String rebuildidx(String
sFieldName)
- Rebuilds the index for a single field.
String
saverec(String[][] sToSave, String sMode)
- Stores one or more records in the database.
String
status()
- Returns the current
error status of the database.
The following
constructors are available for the JRXDbase bean:
JRXDbase()
JRXDbase(String sName, String[][]
sRec)
JRXDbase(String sName)
The above two constructors works as in
the CONNECT method (see below).
The following
methods can be issued on the JRXDbase bean:
String addfield(String sFieldName, String
sFieldLength, String sFieldIndexingMethod)
With this method you can add a field to a
database; you can also specify an index, which will be
built automatically for you.
Notes: Don't use names already in use in
the same database, and specify a valid indexing method
(currently supported: "ISAMxx" and
"NONEx"); The new fields' contents will be
blank for all records (of course). See the
"connect" method for a listing of valid XX, X
values.
String connect(String sName, String[][]
sRec)
This method is the very first to issue, if you have not
instantiated an RXDbase variable with the two-parameters
or one-parameter constructor. If you have, you can omit
this method.
sName is the
name of the file without any extension that is
hosting/will host the database on the disk. RXDbase will
add the file name extension '.dat' to this name.
sRec is a
bi-dimensional Rexx array that has to be built this way:
sRec[0][0] --> Number of fields in the database.
sRec[n][0] --> Length (a whole number stored in a Rexx
variable) of field 'n'.
sRec[n][1] --> Name of field 'n' (it will be used
later).
sRec[n][2] --> Indexing method of the field: it can be
any of the following:
ISAM = Indexed Sequential Access Method, good if you need
to work on the database ordered on this field. Actually,
the current implementation of the indexes is something
like ISAM + B+Trees, but the name ISAM has been kept for
compatibility.
NONE = when you don't do much operations on this field.
More on the indexing: if you want a field not to allow
null values or duplicate
values, you should append an '1' or a '0' to the indexing
string like here:
ISAM00 = ISAM indexing, duplicate and null values are
allowed.
ISAM11 = ISAM indexing, duplicate and null values are NOT
allowed.
ISAM10 = ISAM indexing, duplicate values are NOT allowed,
null values are.
ISAM01 = ISAM indexing, duplicate values are allowed,
null values are NOT.
B+TREE00 = B+TREE indexing, duplicate and null values are
allowed.
B+TREE11 = B+TREE indexing, duplicate and null values are
NOT allowed.
B+TREE10 = B+TREE indexing, duplicate values are NOT
allowed, null values are.
B+TREE01 = B+TREE indexing, duplicate values are allowed,
null values are NOT.
NONE0 = No indexing, null values are allowed.
NONE1 = No indexing, null values are NOT allowed.
As you may have noticed, you cannot specify 'no duplicate
values' for the no-index strategy of indexing.
Notes:
you cannot have currently more
than 1000 fields in a record.
you have to have at least an
index.
when you create a database,
several files will be created.
One, .dat is the real data base;
then, you have a file for every index. This was
done for speed.
String connect(String sName)
This method simply connects to an
existing database (sName is the name of the file).
String definefilter(String sFilter)
By means of this method you can specify a
filter with which all subsequent loadrec
calls will have to comply.
Parameters:
sFilter = an expression,
which can have nested expressions in parenthesis.
Separate filter conditions with | (OR condition) and
& (AND condition).
Example: name =
rob* | surname = kol* will
search for every person whose name starts with 'rob' or
whose surname starts with 'kol'.
Note:
Valid filter conditions are:
<fieldname> <operator> <value>
Where <fieldname> is a valid field name, e.g.
'Name'.
<operator> can be one of the following:
=,<>,>,>=,<,<=
<value> is a valid value for that field, e.g.
'Robert'
Wildcards are allowed only for the = and <>
operators, and they are represented by the symbol '*',
which means "every number of any character".
So, Ro* can be Robert, Ronald, etc. *t can be Matt,
Robert, etc.
M*t can be Matt, mount, etc. (The search is always
case-insensitive)
You can use only one '*' on a given filter (e.g. you
can't query for "Name = *u*i*l*"), with the
notable exception of the form *value*, which means
"find a substring anywhere that is equal to
'value'".
Example: "Telephone = *555*"
will search for all phone numbers with a 555 in them.
Your filter conditions will not produce anything until
the next LOADREC method is issued, from them on all the
calls to LOADREC will use your filter. When requesting
records, if a filter condition is present, the
information about the absolute position on the index of
the records will not be meaningful.
If you specify a filter condition when another one is in
use, the first one will be dropped, and the most recent
one will be used.
Passing the null string or the "" value will
reset the filter conditions.
String delerec(String[] sToDele, boolean
bDelete)
Delerec is used to delete/undelete one or
more records.
sToDele[0]
has to be the total number of records to be (un)deleted,
and sToDele[n] is the ACTUAL position of the n-th record
to be (un)deleted on the database (NOT A NUMBER RELATIVE
TO AN INDEX).
The first record on the database is 1 (one).
When bDelete = true, the
records are to be deleted,
when bDelete = false, the records are to be undeleted.
No errors will come by deleting an already deleted
record, or the other way around. Modirec returns one of
the standard RXDbase error codes.
String deletedb(String sDbName)
This method deletes an entire database,
indexes and all.
String delfield(String sFieldName)
With this method you can delete a field
from a database, including indexes (if any).
Note: As ever, sFieldName can be the name
of the field (ie, 'name') or the number which references
the field (ie, '4', if the 4-th field is 'name').
Warning: The field will disappear *physically* from the
archive. No undo, no restore, zippo.
String disconnect()
Simply put, this method closes all the db
activities for the database being used.
String[][] getdbinfo()
This method returns the database
structure (names and field length, along with the number
of fields).
The returned values are: (let's say we
stored the contents in sRec[][])
sRec[0][0] --> Number of fields in the database.
sRec[n][0] --> Length (a whole number stored in a Rexx
variable) of field 'n'.
sRec[n][1] --> Name of field 'n'.
sRec[n][2] --> Indexing method of the field: it can be
any of the following:
ISAMXX = Indexed Sequential Access Method.
B+TREEXX = B+Tree-based indexes.
XX = 00, 01, 10, 11.
NONEX = when you don't do much operations on this field.
X = 0, 1.
See the "connect" method
for a listing of valid XX, X values.
String[] getdbstats()
This method returns some useful
statistics about the database.
This function returns an array in which:
Element 0 of the array is the db size in bytes.
Element 1 is the record size in bytes.
Element 2 is the total number of records in the database.
Element 3 is the number of active records (not marked
with 'N') in the database.
String[] getdbstatus()
This method lets you retrieve the RXDbase
revision and the presence of a filter.
Returns:
sVar[0] = "No Filter" or "Filter
Present" or "No DB loaded"
sVar[1] = RXDbase version number (e.g. "RXDbase 1.0
Max Marsiglietti 1997").
String globalrebuildidx()
With this method you can rebuild all the
indexes of the database currently in use. Useful to
correct errors, or to restore all the indexes after a
backup+restore. (This way if you need to backup your
archives, you can backup only the .dat file, and issueing
the globalrebuildidx method after the restore you will
get back all of your indexes).
String[][] loadrec(String sIdx, String
sHowManyRec, String sStart, boolean bForward)
Loadrec loads in memory a number of
records from the database. If a filter has been defined
with the definefilter method,
it will be used; otherwise, no record filtering will
occur.
sIdx is an
EXISTING index to use as a reference. It can be a number
(i.e. sIdx = 1 means 'the index on the first field') or a
name (that field's EXACT name, i.e. "Name").
sHowManyRec is the number of
the records to be loaded, ie '72'. It can also have the
value 'ALL', meaning you want all of the records from
sStart on.
sStart is the starting
record. The first record is labeled '1'. A valid value
for this variable is also 'LAST', which means 'go to the
last record'.
bForward If
"true", it means take sHowManyRec records
starting from sStart on (ascending order), else it means
take them from sStart back (descending order).
It returns a bidimensional array which is structured this
way:
sArray[0][0] is the number of records that satisfy the
filter condition(s).
sArray[0][1] is the number of records which are actually
being returned (please use this, and not [0][0], to know
how many records have been returned).
sArray[n,m] is the field n of record m (m = 1 to
rArray[0][0]).
sArray[N+1][m] can be "Y" or "N",
depending on the given record: "Y" means
active, "N" means deleted (only active records
are returned, as of this
release).
sArray[N+2][m] is the position of the m-th record on the
archive (NOT on the index).
sArray[N+3][m] is the position of the m-th record on the
used index (NOT on the archive); this information is
meaningless if a filter is present.
String[,] loadrecwithfilter(String sIdx,
String sHowManyRec, String sStart, boolean bForward,
String sFilter)
This method lets you perform a loadrec
with a certain filter, then reset the filter to whatever
it was before.
The parameters exactly match the ones in
methods loadrec and definefilter.
String modfieldidx(String sFieldName,
String sFieldIndexingMethod)
Modfieldidx lets you modify the indexing
method for a given, existing, field. It automatically
rebuilds the index, if passing from no index to some kind
of index. It is useful if you decide that you don't need
anymore an index, or if you think that you should have
put an index on a field at database definion time, but
you didn't.
Note: sFieldIndexingMethod can be one of
the following:
ISAM00 =
ISAM indexing, duplicate and null values are allowed.
ISAM11 = ISAM indexing, duplicate and null values are NOT
allowed.
ISAM10 = ISAM indexing, duplicate values are NOT allowed,
null values are.
ISAM01 = ISAM indexing, duplicate values are allowed,
null values are NOT.
B+TREE00 = B+TREE indexing, duplicate and null values are
allowed.
B+TREE11 = B+TREE indexing, duplicate and null values are
NOT allowed.
B+TREE10 = B+TREE indexing, duplicate values are NOT
allowed, null values are.
B+TREE01 = B+TREE indexing, duplicate values are allowed,
null values are NOT.
NONE0 = No indexing, null values are allowed.
NONE1 = No indexing, null values are NOT allowed.
As you may have noticed, you cannot
specify 'no duplicate values' for the no-index strategy
of indexing.
String modfieldlength(String sFieldName,
String sNewLength)
This method lets you change the length of
a field.
Note: All the information in excess of
the new length will be lost.
Note2: As ever, sOldName can be a number (eg. '4' meaning
the 4th field) or a name (eg. "surname").
String modfieldname(String sOldName,
String sNewName)
This method lets you change the name of a
field.
The field with name sOldName will get
sNewName name.
Note: As ever, sOldName can be a number (eg. '4' meaning
the 4th field) or a name (eg. "surname").
String modirec(String[][] sToModi)
Modirec is used to modify one or more
records in the database.
sToModi is
to be built this way:
sToModi[0][0] is the total number of records to be
modified
sToModi[n][m] is field n of the m-th record to be
modified. n and m always start from 1 (one).
sToModi[0][m] is the ACTUAL number of the record in the
database (NOT A NUMBER RELATIVE TO AN INDEX) to be
overwritten. This information is the same of the [N+2][m]
element in the loadrec method. The
first record in the database is marked as '1'.
Warning: this method doesn't update single fields, it
overwrites whole records.
Note: there is not an order on the records to be
modified, i.e. you can have:
sToModi[0][1] = 5
sToModi[0][2] = 3
sToModi[0][3] = 18
Returns:
An appropriate error message is shown in case of errors,
else you will be returned a Rexx string, in which every
character is either '0' or '1', where '0' means that the
specified record was not succesfully saved (a null value
where nulls weren't allowed, or a duplicate value where
there sholdn't be any) and a '1' means that the record
was saved succesfully.
Example:
If we try to save 3 records and we get '010' back from
modirec, this means that only the 2nd record among the
ones passed to modirec was succesfully stored in the
database: the remaining two were discarded (probably
because they had duplicated values for fields in which we
specified that no duplicate values should be allowed).
String
pack()
When you delete a record by means of the
DELEREC function, that record doesn't physically get
deleted from the archive, it is instead marked as
'deleted'.
PACK does what the name suggests, it permanently deletes
records from the archive, updating automatically all the
indexes.
String rebuildidx(String sFieldName)
This method is similar to
globalrebuildidx, but must be invoked explicitly on an
index.
Note: As ever, sFieldName can be the name
of the field (ie, 'name') or the number which references
the field (ie, '4', if the fourth field is 'name').
String saverec(String[][] sToSave, String
sMode)
This method lets you write a record on
disk. All of the indexes are automatically updated.
sMode can
only be 'overwrite' or 'append' (case isn't
significative).
sToSave is
to be built this way:
sToSave[0][0] --> number of records to be written.
sToSave[n][m] --> field n of record m.
Warning:
both n,m are to start from 1 (one).
Warning: When you specify
'overwrite', the whole database will be
overwritten (deleted), and the indexes will be resetted.
Returns:
An appropriate error message is shown in case of errors,
else you will be returned a Rexx string, in which every
character is either '0' or '1', where '0' means that the
specified record was not succesfully saved (a null value
where nulls weren't allowed, or a duplicate value where
there sholdn't be any) and a '1' means that the record
was saved succesfully.
Example:
If we try to save 3 records and we get '010' back from
saverec, this means that only the 2nd record among the
ones passed to saverec was succesfully stored in the
database: the remaining two were discarded (probably
because they had duplicated values for fields in which we
specified that no duplicate values should be allowed).
String status()
With this method, you can query the
internal status of the database.
Possible return values are:
DBNOTSTARTED: (can't work on
nothing)
READY: (no errors)
SYNTAX ERROR: (go figure)
ERROR:FILE ACCESS PROBLEMS
(something weird at file level)
|