Java OBjEX User Guide

Authority: Steve Waters Date: 10th August 2006

Information in this document is subject to change without notice.

No part of this document may be reproduced or transmitted in any form or by any means,
electronic or mechanical, for any purpose, without the express written permission of TEMENOS Holdings NV.
Java OBjEX User Guide

Copyright
Copyright (c) 2005 TEMENOS HOLDINGS NV
All rights reserved.
This document contains proprietary information that is protected by copyright. No part of this
document may be reproduced, transmitted, or made available directly or indirectly to a third party
without the express written agreement of TEMENOS UK Limited. Receipt of this material directly from
TEMENOS UK Limited constitutes its express permission to copy. Permission to use or copy this
document expressly excludes modifying it for any purpose, or using it to create a derivative therefrom.

Acknowledgements
Information regarding Unicode has been provided in part courtesy of the Unicode Consortium. The
Unicode Consortium is a non-profit organization founded to develop, extend and promote use of the
Unicode Standard, which specifies the representation of text in modern software products and
standards. The membership of the consortium represents a broad spectrum of corporations and
organizations in the computer and information processing industry. The consortium is supported
financially solely through membership dues. Membership in the Unicode Consortium is open to
organizations and individuals anywhere in the world who support the Unicode Standard and wish to
assist in its extension and implementation.
Portions of the information included herein regarding IBM’s ICU has been reprinted by permission
from International Business Machines Corporation copyright 2001
jBASE, jBASE BASIC, jED, jSHELL, jLP, jEDI, jCL, jQL, j3 j4 and jPLUS files are trademarks of
TEMENOS Holdings NV.

REALITY is a trademark of Northgate Solutions Limited.

PICK is a trademark of Raining Data Inc.
All other trademarks are acknowledged.

Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun
Microsystems, Inc. in the United States and other countries.
Windows, Windows NT, and Excel are either registered trademarks or trademarks of Microsoft
Corporation in the United States and/or other countries.
UNIX is a registered trademark in the United States and other countries licensed exclusively through
X/Open Company Limited.
Other company, product, and service names used in this publication may be trademarks or service
marks of others.

TEMENOS Internal Distribution Page 2 of 15 11/08/2006

Java OBjEX User Guide

Errata and Comments

If you have any comments regarding this document or wish to report any errors in the documentation,
please document them and send them to the address below:

Technical Publications Department

TEMENOS UK Limited
2 Peoplebuilding
Hemel Hempstead
Hertfordshire
HP2 4NW
England
Tel SB: +44 (0) 1442 431000
Fax: +44 (0) 1442 431001

Please include your name, company, address, and telephone and fax numbers, and email address if
applicable. [email protected]

Issue Modification History

Issue Date Changes Made
1 10/08/206 Initial Version

TEMENOS Internal Distribution Page 3 of 15 11/08/2006

Java OBjEX User Guide

Contents
Introduction .............................................................................................................................................. 5
Overview.................................................................................................................................................. 6
Implementation Notes.............................................................................................................................. 7
The Jbase object.................................................................................................................................. 7
Jbase object methods .......................................................................................................................... 8
Sample Java Program ......................................................................................................................... 9
Notes .............................................................................................................................................. 10
Java Exceptions ............................................................................................................................. 10
Documentation ............................................................................................................................... 11
Startup................................................................................................................................................ 12
Starting on Unix.............................................................................................................................. 12
Starting on Windows ...................................................................................................................... 12
Log file ............................................................................................................................................ 14
Environment Settings ..................................................................................................................... 14
OBjEXNET............................................................................................................................................. 15

TEMENOS Internal Distribution Page 4 of 15 11/08/2006

Java OBjEX User Guide

Introduction
Java OBjEX provides a programming interface from Java applications to directly access jBASE
functionality on a Server. It provides classes and associated methods to perform very similar actions
to that in BASIC, e.g. OCONV, READU, INDEX. This has the advantage that existing BASIC
programmers can program in Java using familiar concepts, enabling them to become productive very
quickly. Almost all keywords and functions are implemented as classes and methods, with the
exception of those which are not relevant to be supported.
Java OBjEX allows the development of distributed Client Server applications, with the client
connecting to a server component via RMI, with the latter providing the interface into jBASE itself. All
file I/O is handled by the jEDI interface, which ensures that all locking is respected, and that the
application behaves as ‘just another jBASE’ user.
Java OBjEX is packaged as a jar file making it easily distributable, and is available on the standard
release on all jBASE supported platforms. An Enterprise user licence is required in order to enable it.
The obvious advantage of using Java OBjEX is one of integration. You can modify existing legacy
Java applications to provide access to, and interaction with jBASE, or write new applications as
desired.

TEMENOS Internal Distribution Page 5 of 15 11/08/2006

Java OBjEX User Guide

Overview

Java OBjEX is an API which allows any Java program to interact with the jBASE database and
application system. It aims to duplicate the functionality available from a jBASE BASIC program as far
as is practical. As you would expect, you can open, read and write files and indices directly, but in
addition, you can also work with Dynamic Arrays holding attributes, multivalues and subvalues, and
perform OCONV, DCOUNT and other methods familiar to the BASIC programmer. The package itself
uses JNI technology to directly call the functions of jBASE, so all aspects of locking, sessions,
licensing etc are managed by the jBASE Server as if the Java program were a normal jBASE session.

Because of Java’s platform independent architecture, any application using Java OBjEX can be
immediately deployed on any platform supported by jBASE, or any mix of platforms between client
and server.

The API is packaged as a typical Java jar file (javaobjex.jar), and just needs including in the
CLASSPATH for compilation and execution of the Java application. There are two ways of using JO,
either standalone or client server.

The first method of operation is self contained, with all of the jBASE functionality residing on a single
machine, which is useful for development and module testing. The client server model is more likely to
be deployed in a production environment, with multiple clients connecting to a jBASE Server.

For Client Server operation, a Java OBjEX Server component daemon must be started on the Server,
and the client program uses RMI technology to access the server. For programs developed in
standalone mode, the only code change required to migrate from standalone to client server, is to
specify the jBASE object as remote. In fact, since the JO Server can be started on a standalone
machine, and’localhost’ specified as the ‘remote’ server, all testing can be carried out locally, and then
simply change ‘localhost’ to ‘jBASE Server name’.

TEMENOS Internal Distribution Page 6 of 15 11/08/2006

Java OBjEX User Guide

Implementation Notes

The following notes show how to implement Java OBjEX in a Java program, with a simple example to
illustrate this more fully:

The Java program should specify an import statement for the package e.g.
import com.jbase.javaobjex.*;

The Jbase object

In order to access jBASE, the key object is the Jbase object which represents the jBASE engine. As
the top-level object, it contains and controls all other objects in the hierarchy of objects. For ease of
maintainability you are advised to use the name jB for all references to the jBase object. This
documentation will use jB whenever a reference is made to the jBase object
Typically you would only need a single instance of Jbase for a program. To instantiate a simple
standalone object add the following:

Jbase jB = new Jbase();

This instantiates a Jbase object on the local machine therefore there must be a copy of jBASE
installed here. All subsequent connections and activity interact with the local jBASE database, and
therefore it is not required to start JavaOBjEXServer.

To instantiate a remote Jbase object, invoke the constructor that takes Server Name (or IP address)
as a parameter, with a port number appended. This method causes a Jbase object to be instantiated
via the JO Server running on the specified server.
Note that the first example is for running locally within the same machine via the JO Server. The
second refers to an actual remote server upon which it is assumed that JO Server is running along
with the jBASE database. All subsequent connections and activity will therefore interact with jBASE on
that server.

Jbase jB = new Jbase(“localhost”);

or
Jbase jB = new Jbase(“jbase_svr”);

Note that the JO Server must be already started on the specified server for this to succeed.

TEMENOS Internal Distribution Page 7 of 15 11/08/2006

Java OBjEX User Guide

Jbase object methods

Here is a sample of the methods exposed by the Jbase object:

connect ( ) make a connection to Jbase object.

connectJDBC ( ) make a JDBC connection to Jbase object.

date ( ) return today’s date in internal jBASE format.

time ( ) return current time as seconds since midnight.

newJdynArray ( ) create a Dynamic Array object (jBASE variable).

terminate ( ) terminate the Jbase object.

Now that we have a Jbase object, the first method that must be invoked is connect() e.g.

Jconnection jC = jB.connect();

The Jconnection object exposes a varied collection of methods with just a few examples below:
open, openDict open a jBASE file or dictionary
openSeq open a flat file
transStart, transEnd Transaction control
createCommon create a COMMON variable block
call, execute CALL a jBASE subroutine, or EXECUTE a command line

From here we start to see the typical hierarchy of Java ObjEX objects. For more details consult the
comprehensive JavaDoc documentation which is supplied with jBASE, and can be viewed in any
browser by opening the ‘index.html’ file.

TEMENOS Internal Distribution Page 8 of 15 11/08/2006

Java OBjEX User Guide

Sample Java Program

Probably the best way to proceed at this point is with a simple code example. In the example
belowyou can see how the hierarchy of objects fit together in a way which will be familiar to any Java
programmer.
This program opens the file CUSTOMERS, creates a Select List, and then iterates through the list until
exhausted, after which the file is closed and the program terminates.

import com.jbase.javaobjex.*;
public class JOtest { public static void main(String args[]) {
Jbase jB = null;
Jconnection jC = null;
JdynArray jd1 = null;
Jedi f1 = null;
JselectList js1 = null;
String key1 = null;
String list1 = null;
String s = null;
try { // Instantiate Jbase object and connect
jB = new Jbase(“localhost”);
jC = jB.connect();

// Open a file
f1 = jC.open("CUSTOMERS");

// Create a select list

js1 = f1.select();

// Read the file – use the JselectEndException to detect end of file

try {
while(true) {
key1 = js1.readnext();
jd1 = f1.read(key1);
s = jd1.toUnicodeString();
System.out.println("Record " + key1 + " = " + s);
}
} catch(JselectEndException see) {
System.out.println( "End of File!");

TEMENOS Internal Distribution Page 9 of 15 11/08/2006

Java OBjEX User Guide

// Catch any other exceptions

} catch(Exception ee) {
System.out.println( ee.getMessage());
System.exit(1);
}
// All done, so close file
try {
f1.close();
} catch(Exception c) { }

} catch(Exception e) {
System.out.println("jBASE Error! – “ + e.getMessage());
System.exit(2);
}
// Disconnect and terminate Jbase object
try {
jc.disconnect();
jb.terminate();
} catch(Exception e) { }

jb = null;
System.out.println("terminating\n");
}

Notes
Notice how the exception JselectEndException is used to detect the end of the Select List and break
out of the while loop.
This program establishes a connection with the Java OBjEX Server on the same machine. In order to
avoid an error indication, ensure that the Server has been started successfully before running (see
below).

Java Exceptions

Program Exceptions can be caught in the normal way. See the JavaDoc documentation for details of
class specific Exceptions that can be thrown.

Note that due to the limitations of Java RMI, when executing in client server mode, exception handling
is limited to raising of RemoteExceptions on the client, from methods executing on the Server, and
hence some additional analysis of the exception message will be necessary to establish the exact
cause of the original exception.

TEMENOS Internal Distribution Page 10 of 15 11/08/2006

Java OBjEX User Guide

Documentation
The JavaDoc documentation is located in the jBASE release directory in the Help folder. Select the
javaobjex folder therein, and double click index.html file to open the document files in the local
browser.

TEMENOS Internal Distribution Page 11 of 15 11/08/2006

Java OBjEX User Guide

Java OBjEX Server

The JavaOBjEX Server is the background server component which provides the interface services
between a Java program and the jBASE system. Client applications each make a connection to it via
RMI in order to utilize its services as described above.

Startup
The JO Server must be started before any of its services can be provided. To start it enter:

javaOBjEXServer start

Output to screen as follows (or similar):

JBCRELEASEDIR = /home/jbc
JBCGLOBALDIR = /home/jbc
JREDIR = /var/java/jre
TEMENOS javaOBjEX Server
-----------------------------------------
Requested Action..................> START
Check if it's already running.....> NO
Starting..........................> OK
Started and ready on <:3570>

Starting on Unix
On Unix the JO Server will run as a background process, which can be initiated using an ‘rc’ type script at system
startup if required.

Starting on Windows

From a Command Prompt

On Windows there are two possible modes of operation. The above command can be entered at a command
prompt, or stored in a shortcut, and, when executed, a separate command window will be created to represent the
process.

TEMENOS Internal Distribution Page 12 of 15 11/08/2006

Java OBjEX User Guide

Installing as a Windows Service

Alternatively, the JO Server can be installed as a Windows service using the following command:
javaOBjEXServer install

Output to screen as follows (or similar):

"JBCRELEASEDIR = E:\jbase4/4.1"
"JBCGLOBALDIR = E:\jbase4/4.1"
"JREDIR = C:\jdk1.4\jre"
wrapper | Temenos javaOBjEXServer installed.

Examining the list of services (Administrative rights required) will show the new service called “Temenos Java
OBjEX Server”. Installation is permanent and only needs to be done once. If the service is to be removed, the
command
javaOBjEXServer remove
will delete the service from the list.
Once installed, the service can be configured in the usual way, by right clicking the name and selecting the
Properties dialog, in which Automatic startup mode can be set to start the JO Server at boot time.

TEMENOS Internal Distribution Page 13 of 15 11/08/2006

Java OBjEX User Guide

Log file
The JO Server writes to a log file which is located in $JBCRELEASEDIR/logs
(or %JBCRELEASEDIR%\logs on Windows). This records the start and stop actions and any error
conditions encountered, and is particularly useful when running as a Windows Service for diagnosing
any startup problems which may occur.
Sample entries:
STATUS | wrapper | 2006/08/10 15:59:06 | --> Wrapper Started as Service
STATUS | wrapper | 2006/08/10 15:59:07 | Launching a JVM...
INFO | jvm 1 | 2006/08/10 15:59:09 | start service
INFO | jvm 1 | 2006/08/10 15:59:10 | Service started correctly

STATUS | wrapper | 2006/08/10 16:33:20 | Service is running. Stopping

it...
INFO | wrapper | 2006/08/10 16:33:21 | Waiting to stop...
STATUS | wrapper | 2006/08/10 16:33:22 | <-- Wrapper Stopped
STATUS | wrapper | 2006/08/10 16:33:22 | Temenos javaOBjEXServer stopped.

The entries above are generated by the default logging level, which is set in a configuration file called
$JBCRELEASEDIR/logs/javaobjex.properties. Look for the section called LOGGING PROPERTIES
and note the levels ranging from 0 to 7. As the level value increases, more logging detail is recorded
to the log file. The level is set by server.log.level=x, with x as the required level. Once the level
has been change, this will not take effect until JO Server is restarted.
NOTE that increasing the logging level can have a marked effect on performance, and should only be
changed for problem diagnosis rather than for normal operation.

Environment Settings
It is very important that the jBASE environment variables are set to the correct values so that user
account information, data files, subroutines etc are all accessible. This must be done in the same
session that JO Server is started from, before it is started. Failure to do this is the most common
cause of runtime problems reported by clients. Typical variables to be set are as follows:
JBCRELEASEDIR
JEDIFILEPATH
JBCOBJECTLIST
JEDIFILENAME_MD
JEDIFILENAME_SYSTEM
However this not an exhaustive list. As a rule of thumb, the environment should be set up as if running a BASIC
program performing the same actions as the Java.

Windows Service Environment

When running JO Server as a Windows Service, the System environment variables must be set up before the
service is started. See Control Panel -> System -> Advanced -> Environment Variables.

TEMENOS Internal Distribution Page 14 of 15 11/08/2006

Java OBjEX User Guide

OBjEXNET
There is a parallel product to JavaOBjEX called OBjEXNET. This enables Microsoft .NET applications
to access all of the facilities of JO Server in the same way as from a Java program. It operates in a
very similar fashion, and is packaged as a .NET assembly dll file. Refer to the jBASE samples
directory for examples and full documentation of the product.

TEMENOS Internal Distribution Page 15 of 15 11/08/2006