Using DataBasic Objects

DataBasic objects (DBOs) are opaque variables that reference an internal or external object. They can be copied, compared and deleted like any other variable but cannot be directly used in arithmetic or string operations.

Accessing elements of a DataBasic object uses the new -> operator, which is similar in use to the "." (dot) operator in many object-orientated languages.

Object Error Handling

Object errors are treated as DataBasic exceptions and, once code is developed, it is recommended that an exception handler is always defined to catch any exceptions that may be thrown by the object. If no exception handler is defined, any errors generated by the DataBasic Object in run time will be treated as fatal and trapped by the DataBasic debugger.

Using Java Objects in DataBasic

Java objects are a subset of generic DataBasic objects.

Java objects are used in DataBasic as you would if writing Java code to run in a true Java environment, the main exception being that the Java "." operator is replaced with the DataBasic "->" operator.

The objects and their associated Java statements are created and processed by a Java language server under the control of the DataBasic run time.

To support object-orientated language syntax (e.g. 'new'), a set of special methods is available. Special methods always have a % character prefix (e.g. %NEW) to identify them from standard Java objects.

Java is a heavily typed language in contrast to DataBasic where variables are largely untyped. Because of this it is possible for the data type of method arguments to be ambiguous. A new 'cast' syntax has been introduced to DataBasic to alleviate this problem. A variable can be explicitly cast to a type by using a cast statement. For example, "(int16)Var" forces Var to take the type of a 16-bit integer for the purposes of a method call.

Note that the DataBasic compiler knows nothing about objects in the Java world so it is easy to write and compile code that is syntactically incorrect. Problems like incorrect/mistyped method names/signatures will not be noticed until run time. Hence it is strongly recommended that when developing code, the program is run with the (F option, or run with the FATAL.WARNINGS custom option set, to force unassigned variables to trap into the DataBasic Debugger to catch errors as early as possible.

Java Object Examples

Examples of using Java Objects to create a PDF and an Excel spreadsheet using data in the HOTEL account are available in /SYSPROG/BP as ROOMS.PDF and ROOMS.XLSX respectively. These examples require third party Java packages to be installed before they can be used. See the comments in the examples.

Connecting to a Language Server

Before any Java objects can be created or used a connection must be made to a Java Language Server.

For example:

%CONNECT(JAVA)

Creates a connection to the language server on the local host. The first connection made automatically becomes the default connection.

Importing the Java Code to be Used

Once a connection object has been created it has to be associated with any required packages. Java packages are usually stored in libraries that are held in a jar file on the system running the language server. The %IMPORT special method behaves much like the Java import statement.

Note that the first parameter to a special method (%IMPORT in this case) is a key word.

For example:

%IMPORT(java.io)

Imports the "java.io" package.

For more information, see Special Methods for Connector Objects.

Creating Objects

Once there is a connection object %NEW can be used to create DBOs. An object is instantiated within the language server and this object is associated with a DataBasic variable (DBO). The first parameter is the class name, which can be followed by a comma-separated list of initialisers.

For example:

Obj = %NEW(String, "My string")

Creates a new string object and initialises it to "My string".

For more information, see Special Methods for a Java Object.