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) |