3 Basic Database Features

Let's start with a simple address management application.

For now, we will assume that gnue-appserver has been installed properly and is already running, that gnue-forms and gnue-reports are also installed, and that your connections.conf file is set up correctly to allow connections to the running application server with the [appserver] connection.

3.1 General GCD Layout

To define the classes for GNU Enterprise, we use GCD files (GNUe Class Definition files). These files are a specialized XML file format. You can write GCD files with any editor you want.

So for a start, let's look at a very simple GCD file:

     <module name="address">
       <class name="person">
         <property name="name"   type="string(35)" />
         <property name="street" type="string(35)" />
         <property name="zip"    type="string(8)" />
         <property name="city"   type="string(35)" />
       </class>
     </module>

3.2 Using GCD Files

After having written the above GCD file, save it as `address.gcd' and stop gnue-appserver. Now we have to make GNU Enterprise read and process our class definition. We do this by typing

     gnue-readgcd address.gcd

at the command prompt. This will teach GNU Enterprise about our new class and make the database backend create the tables necessary to hold the data of this class. You can re-run gnue-readgcd as often as necessary and the database will be inserted/updated, but elements will not be deleted. Restart gnue-appserver.

Please note that some databases may allow adding new tables while there is an active connection to the database server. You may not have to stop gnue-appserver depending on the database selected.

As an alternative, GNU Enterprise supports a configuration option called the module path. You can simply place your GCD files (and also the GLD files we will learn about later) into any directory given in that path or into a subdirectory of any of these directories, send the gnue-appserver process a SIGHUP signal, and GNU Enterprise will read in the GCD files automatically. However, this does not work under Windows.

Now, as GNU Enterprise has learned about our class, we are ready to display a form and enter data: type

     gnue-forms appserver://appserver/form/address_person

and enjoy your first application!

Please note the syntax of the last part in the command line, consisting of the module name, an underscore, and the class name. We call this the fully qualified class name.

You will probably notice that the form doesn't look very good yet. Of course we will improve that later, but first let us analyze the content of our little example file so far.

3.3 Modules

The outermost level in the XML hierarchy, the root element, is the module. Everything we define in a GCD file is defined within a module, and you can have exactly one module per GCD file.

The following attributes are valid for the module tag:

name

unique name of the module, namespace identifier for everything defined within the module (max. 35 characters, but usually not more than 10 characters, can not include underscore character, required)

comment

explanatory text, not used by the system in any way (max. 70 characters, optional)

3.4 Classes

Naturally, we start the module by defining a class. The class tag can have the following attributes:

name

identifier for this class, has to be unique within the module (the length of this name plus the length of the module name should not exceed 30 characters, can not include underscore character, required)

comment

explanatory text, not used by the system in any way (max. 70 characters, optional)

module

may only be given if a class of a foreign module is extended; don't let this confuse you, this will be explained later, we've just put it here for the sake of completeness

3.5 Properties

The most important building blocks of a class definition are property tags, defining the data fields of the class. These attributes can be given for a property tag:

name

identifier for the property, has to be unique within the class (except for the case of class extension) (the length of this name plus the length of the module name should not exceed 30 characters, required)

comment

explanatory text, not used by the system in any way (max. 70 characters, optional)

type

data type of this property, see below (required)

length

maximum length of data stored in this property, if appropriate for the data type (optional)

scale

scale of data stored in this property, if appropriate for the data type (optional)

nullable

`true' means the value of None is valid for this property, while `false' means it is not (optional, defaults to `true')

3.6 Data Types

GNU Enterprise supports the following basic data types:

string

Strings can hold arbitary text. A length may be given and means a maximum length of the text; if no length is given, maximum length is limited only by the database backend in use. As long as the backend supports Unicode, there is no limitation on the characters that may appear in the string.

number

Numbers can be defined with length only (meaning integers with the given maximum number of digits) or with length and scale (meaning a maximum number of digits as given in length, where exactly the number of digits given in scale are after the decimal point).

boolean

Booleans can only hold TRUE or FALSE. Neither length nor scale may be given for booleans.

date

The valid range of dates depends on the capability of the database backend. Neither length nor scale may be given for date properties.

time

This stores an absolute time value and is heavily dependent on the database backend. Future versions of GNU Enterprise might have features to unify the handling of time values for the different databases, but until then, time properties are not recommended. Neither length nor scale may be given for time properties.

datetime

Datetime properties store a date and a time, often also called a timestamp. The valid range as well as the resolution depends on the database backend, and it is generally not recommended to use fractions of seconds as not all databases support this. Neither length nor scale may be given for datetime properties.

Length and scale may also be given in the type attribute, after the name of the type, enclosed in parathenses, with a comma between length and scale. So

     <property name="foo" type="string(35)" />
     <property name="bar" type="number(12,2)" />

is equivalent to

     <property name="foo" type="string" length="35" />
     <property name="bar" type="number" length="12" scale="2" />

3.7 Implicit properties

For every class, GNU Enterprise implicitly creates a few properties:

gnue_id

is a non-changeable string property with 32 characters. GNU Enterprise automatically assignes a unique random string for every new instance that is created. The value of gnue_id will remain constant for a given instance until it is deleted. The underlying column in the database table, also called gnue_id, serves as the primary key for the table.

gnue_createdate

holds the date and time of the creation of an instance.

gnue_createuser

holds the user name that created the instance, in case GNU Enterprise is configured for user authentication.

gnue_modifydate

holds the date and time of the last modification to this instance. It can be empty if an instance hast just been created and is still in virgin state.

gnue_modifyuser

holds the user name that did the last modification to this instance, in case GNU Enterprise is configured for user authentication. It can be empty if an instance hast just been created and is still in virgin state.