Frequently Asked Questions

When installing the driver, two files are deployed to a library directory as follows.

Driver, which has an extension such as .dll, .so, .sl depending on the operating system

Text file with the same name as the driver file with typically an .el or .def extension. The text file lists the jBASE entry points to the driver.

This directory path must be included in the JBCOBJECTLIST environment variable. If jBASE is unable locate the text file and driver, the following generic error is displayed indicating that the illegal file operation command is passed to jedi.

** Error [ JEDI_FILEOP_ILLEGAL_CMD ] **

In case of this error, you need to check the correctness of the parameters supplied on the command line, use a command like jshow –v XMLDDDInit, and check that the driver and .el file are listed in the returning output. If not, the JBCOBJECTLIST has not been set up correctly.

Typically, any error that occurs in the driver are written to the XMLdriver.log file in the current directory. If the JEDI_XMLDRIVER_TRACE environment variable is set, the driver will also write additional trace information to the file. You can examine this file to see the operations driver has performed. It is recommended that this logging option be not switched on permanently, as the log file tends to become huge soon.

Creating a file in the driver can be done either programmatically or from the command line. The syntax for creating the file is as follows.

CREATE-FILE <FILENAME> TYPE=XMLMSSQL|XMLORACLE|XMLDB2 [NOXMLSCHEMA=YES] [SIZE=LARGE]

Issuing the command will locate the driver and call routines from the known interface to carry out the function. The runtime engine is not neither aware of what occurs within the driver, nor that the target database is RDBMS. It is the responsibility of the driver to perform all the relevant RDBMS specific commands. If any call to the driver fails, the driver writes the specific RDBMS error message to the log file and returns a relevant and generic JEDI_FILEOP_FAIL error. If the operation was successful, it indicates that the driver has created the following.

• Data and dictionary STUB files on the local driver

• Two tables in RDBMS one each for data and dictionary

• Two new entries in the RDBMS STUBFILE table

The NOXMLSCHEMA=YES option in the CREATE-FILE command is not mandatory. If it is used, the XMLREC column in the RDBMS database will be of BLOB (Binary Large Object) type.

After a CREATE-FILE command is issued and driver has been located through the .el or .def file, the driver can begin the process of creating the actual files and tables.

When the runtime initialises the driver, the driver checks for any existing connections. If no connection is currently open, the driver connects to the database. In the log file, this operation is indicated by the following block of code.

14560 - 2.0.0 - Wed Feb 12 13:27:56 - Initialising Driver Data
 14560 - 2.0.0 - Wed Feb 12 13:27:56 - Current open connection count = 0
 14560 - 2.0.0 - Wed Feb 12 13:27:56 - Mutex Lock
 14560 - 2.0.0 - Wed Feb 12 13:27:56 - Mutex UnLock

In this particular example, versions used are XMLRDBMS driver 3.0.x and jBASE Version 5.0.

The first line of the log file shows that the driver is initialized, checked for current open connections and then connected. If the driver was unable to initialise and connect, the RDBMS error message appearing here would indicate that either RDBMS was not available or the log on credentials were not correct.

The driver uses function calls to communicate with RDBMS. These are CLI, OCI, and OLEDB for DB2, Oracle, and MSSQL, respectively.

After the driver is initialised, stub file is created, which is a static file that holds no data. The stub file is given the default permissions for the current Unix user.

14560 - 2.0.0 - Wed Feb 12 13:27:56 - D_DEMO1 - CREATE-FILE: SQL statement:  
 CREATE TABLE

The driver issues a SQL statement to create the first RDBMS table. For each normal jBASE file, MYFILE data file and MYFILE]D dictionary files are created, which need to be created by the driver as well. The dictionary table needs to be created first. Rather than append the illegal characters ]D on to the table name, the driver prefixes the table name with D_ to signify that this is the dictionary file. Using the CLI functions, the driver executes the following SQL statement.

CREATE TABLE D_DEMO1 
 (RECID VARCHAR(200) NOT NULL, 
 XMLRECORD RDBMSxml.xmlvarchar, 
 CONSTRAINT D_DEMO1_PK PRIMARY KEY(RECID)) 

The above SQL statement creates a two-column table in the RDBMS database. The first column is of the VARCHAR(200) type containing the jBASE ITEM_ID (or unique primary key) for the record and is indexed as a primary key.

In the above example, the CREATE-FILE command was issued without the optional NOXMLSCHEMA=YES parameter, which indicates that the data type for the XMLRECORD field is RDBMSxml.xmlvarchar.

14560 - 2.0.0 - Wed Feb 12 13:27:56 - D_DEMO1 - CREATE-FILE: 
 Absolute file path /large/T24/G13101/mbdemo.env/ted/Demo1]D

14560 - 2.0.0 - Wed Feb 12 13:27:56 - D_DEMO1 - CREATE-FILE: STUBFILES 
 SQL: INSERT INTO STUBFILES VALUES(?, ?, ?)

When creating a table, the driver adds a record to the STUBFILES table as a precaution. This record holds the following.

• Location of the stub file that the driver created

• N 678ame of the local table in RDBMS

This enables an easy recreation of the stub files or physical (local) RDBMS table, if required. The final column in the table type indicates the type of column used for the data field.

All the above actions were performed by a single call from jBASE to the JediFileOpCreateXMLRDBMS routine in the driver. The jBASE calling routine has provided all the required parameters including the table name and type (dictionary/data) to be created. When the routine has successfully been called for the first file (in this case the dictionary file for DEMO1) which created the table D_DEMO1 and stub file DEMO1]D, the jBASE engine can then call the same routine again to create the data portion of the file, that is, the table DEMO1 and stub file DEMO1. However, before these creations, a simple write/read/delete test is performed on the file.

The following code shows that the write/read/delete test is performed.

14560 - 2.0.0 - Wed Feb 12 13:27:57 - D_DEMO1 - OPEN: Tablename: D_DEMO1
 14560 - 2.0.0 - Wed Feb 12 13:27:57 - D_DEMO1 - OPEN: End

The following code shows in the log, that the table has been opened

14560 - 2.0.0 - Wed Feb 12 13:27:57 - D_DEMO1 - WRITE: Start
 14560 - 2.0.0 - Wed Feb 12 13:27:57 - D_DEMO1 - WRITE: Tablename: D_DEMO1
 14560 - 2.0.0 - Wed Feb 12 13:27:57 - D_DEMO1 - WRITE: Key: Demo1
 14560 - 2.0.0 - Wed Feb 12 13:27:57 - D_DEMO1 - WRITE: Record: Q
 14560 - 2.0.0 - Wed Feb 12 13:27:57 - D_DEMO1 - WRITE: Record Length: 1
 14560 - 2.0.0 - Wed Feb 12 13:27:57 - D_DEMO1 - WRITE: Writing jBASE record as …
 14560 - 2.0.0 - Wed Feb 12 13:27:57 - D_DEMO1 - WRITE: XML record: 
 <row id='Demo1'><c1>Q</c1></row>

The following code shows a simple string has been written to the file

14560 - 2.0.0 - Wed Feb 12 13:27:57 - D_DEMO1 - CLOSE: Start
 14560 - 2.0.0 - Wed Feb 12 13:27:57 - D_DEMO1 - CLOSE: End

The following code shows that the file is fully closed

14560 - 2.0.0 - Wed Feb 12 13:27:57 - D_DEMO1 - OPEN: Tablename: D_DEMO1
 14560 - 2.0.0 - Wed Feb 12 13:27:57 - D_DEMO1 - OPEN: End

The following code shows that the file is opened again.

14560 - 2.0.0 - Wed Feb 12 13:27:57 - D_DEMO1 - READ: Start
 14560 - 2.0.0 - Wed Feb 12 13:27:57 - D_DEMO1 - READ: key = Demo1
 14560 - 2.0.0 - Wed Feb 12 13:27:57 - D_DEMO1 - READ: SQL statement: 
 SELECT XMLRECORD FROM D_DEMO1 WHERE RECID = ?
 14560 - 2.0.0 - Wed Feb 12 13:27:57 - D_DEMO1 - READ: key = Demo1,
  record = <row id='Demo1'><c1>Q</c1></row>
 14560 - 2.0.0 - Wed Feb 12 13:27:57 - D_DEMO1 - READ: End

The following code shows that the data is read back and verified.

14560 - 2.0.0 - Wed Feb 12 13:27:57 - D_DEMO1 - DELETERECORD: Start
 14560 - 2.0.0 - Wed Feb 12 13:27:57 - D_DEMO1 - DELETERECORD: End

The following code shows the record is deleted.

14560 - 2.0.0 - Wed Feb 12 13:27:57 - D_DEMO1 - OPEN: Tablename: D_DEMO1
 14560 - 2.0.0 - Wed Feb 12 13:27:57 - D_DEMO1 - OPEN: End
 14560 - 2.0.0 - Wed Feb 12 13:27:57 - D_DEMO1 - READ: Start
 14560 - 2.0.0 - Wed Feb 12 13:27:57 - D_DEMO1 - READ: key = Demo1
 14560 - 2.0.0 - Wed Feb 12 13:27:57 - D_DEMO1 - READ: SQL statement:
  SELECT XMLRECORD FROM D_DEMO1 WHERE RECID = ?
 14560 - 2.0.0 - Wed Feb 12 13:27:57 - D_DEMO1 - READ: Record with key Demo1 not found

Finally, a second (concurrent) connection is opened, which attempts to read of the data. The second (concurrent) connection is used to ensure that the data has been deleted at the proper time and not when the original file is closed.

The log file record shows that the write/read/delete test has worked. Now the jBASE engine can repeat the whole process for the second table (the data file).

The CREATE-FILE command is given below.

CREATE-FILE <Filename> [tablename] [noxmlschema] <type>

This command has the following qualifiers.

CREATE-FILE myreallyreallylongtablename TABLENAME=notsolongname TYPE=XML…

CREATE-FILE mytable NOXMLSCHEMA=YES | WORK TYPE=XMLDDD
CREATE-FILE mytable TYPE=XMLDDD

CREATE-FILE data_part_mon TYPE=XMLDDD

By default, the second column in the RDBMS tables (that is, XMLRECORD holds the actual data) is created with the XMLTYPE field type (See the How do I use the XMLTYPE columns? section for information on these functions).

Due to the nature of XML, binary data cannot be held in a XMLTYPE field. If binary data is required, then you should use the BLOB field type. Instead, a BLOB data type is in essence similar to the XMLTYPE but it is not XML aware and does not have the additional functions of the XMLTYPE. When using the BLOB object, SQL statements must be done using the SQL syntax without using the XMLTYPE functions.

When the table is created in RDBMS, a CREATE TABLE SQL statement is issued with the relevant data type:

RDBMSxml.xmlvarchar

CREATE TABLE DEMO1 (RECID VARCHAR(200) NOT NULL, XMLRECORD RDBMSxml.xmlvarchar, CONSTRAINT DEMO1_PK PRIMARY KEY(RECID))

RDBMSxml.xmlclob

CREATE TABLE DEMO1 (RECID VARCHAR(200) NOT NULL, XMLRECORD RDBMSxml.xmlclob, CONSTRAINT DEMO1_PK PRIMARY KEY(RECID))

CLOB

CREATE TABLE DEMO2 ( RECID VARCHAR(200) NOT NULL, XMLRECORD CLOB(1000000), CONSTRAINT DEMO2_PK PRIMARY KEY(RECID))

The XMLTYPE data type is an extended data type that has been made aware of XML. There are limitations on XML types when attempting SQL SELECT statements as shown below.

SELECT XMLRECORD FROM DEMO1 WHERE RECID = ‘…’

In this instance, it is recommended to use create-view and issue the SELECT statement from the resulting view.

Similarly, sample command is shown below when using SQL INSERT statement.

INSERT INTO data_table (RECID,XMLRECORD) VALUES ('1', '<row id="1"><c1>mike</c1></row>')

Because the data held is in XML format, the WHERE clauses used must adopt an XPATH query to retrieve data:

SELECT <field criteria> FROM <table>  WHERE RDBMSxml.extractvarchar (XMLRECORD, '/row/c3[@m=”2”]') = ‘X’

In the above example, the data in between <c3 m=”2”> and </c3> tag structure having a text value of X is matched.

As a precaution, when creating a table, the driver adds a record to the RDBMS STUBFILES table. This record holds the location of the stub file that the driver created and the local table name in RDBMS. This makes easy (if required) to recreate either stub files or physical (local) RDBMS table. The final column of the type table records whether the table used a BLOB or XMLTYPE data field. The driver uses the STUBFILES table only during the ‘file create’ routine when a record is added.

What happens when the driver reads the entire table?

Reading all the data through the driver is multi-step process involving multiple API calls to the driver.

A following pseudo code program explains what occurs during a read process.

SELECT data - Create a select list of ID’s matching any WHERE/WITH criteria
 READNEXT key – Read the first\next ID from the select list
 DO UNTIL ALL RECORD READ
 READ data – Read the actual data record
 READNEXT key – Read the next key in the select list
 CLOSE – Close the select list and connection to the database

When a SELECT list is created, a cursor is opened and maintained on the RDBMS database.

The common jEDI interface routines such as SELECT, READNEXT and READ are used in the driver for reading.

Unlike in an RDBMS, there is no concept of Update vs. Insert so the driver must determine the most effective method to use first.

After the insert is attempted and if it fails with a ‘record already exists’ error, a subsequent update is attempted. In the same versions of the driver, the UPDATE is attempted first (on a per file basis). If this fails, then the driver automatically attempts the relevant method first. This means that groups of updates or inserts is quicker than alternating updates and inserts. Some RDBMSs also support the MERGE statement, and this is used by the driver wherever possible.

The current locking strategy is that the File System Interface layer handles all locking. So, either the jRLA daemon (if activated) performs the locking or the Unix OS file locking mechanism is used.

The jRLA daemon locks the file at item level (Record or Row). Unlike RDBMS, locking in the application only occurs when requested (For example, using a READU command). If the same record is opened twice in an editor, the second instance will be marked as ‘Read Only’.

Unless you use transaction boundaries (such as Begin Trans, Commit Trans and Rollback Trans), records are by default committed after each write. It is not recommended to include large numbers of updates in a single transaction. If the driver fails before the number of writes required for a commit, all prior writes are not committed and saved.

Transaction boundaries such as Begin Trans, Commit Trans and Rollback Trans are all set at the File System Interface level. Then, the driver passes the instructions to begin, commit or rollback a transaction to the RDBMS.

If the transaction boundaries are not in use, then ‘auto commit’ is defaulted such that each INSERT or UPDATE are automatically committed when issued.

A database connection is opened when the application requests data or attempts to write to the RDBMS database. This connection is used for all subsequent file I/O. When the thread for the application closes, the connection is closed.

Applications support internationalisation, and the driver accommodates UTF-8 databases, whereby the default encoding of XML is UTF-8.

Temenos Transact uses transaction management facilities of the database to ensure that transaction data is available as an atomic unit of work. Either all or none of the updates hit the database for the transaction. This is accomplished using the File System Interface transaction management facilities of the run time, such as DB2, Oracle, MSSQL or jBASE’s database.