>> Table of Contents >> Article

Database

Database is the root level element of a XDDL document. It may contain several child elements. Those may be categorized using 5 basic groups: Tables, Views, Forms, Functions and Change-logs. The database element defines basic properties of the database itself, as well as information for the client and applications that may connect with the database.

Element Database

  ELEMENT database (description?, (include | table | view | form | function |
                     sequence | initialization)*, changelog?)
  ATTRIBUTE
       name        string
       title       string
       charset     string
       datasource  string
       readonly    bool
  
Attributes
Attributes Type Mandatory Default Description
name string - n/a An unique name that identifies this database. Defaults to the filename. It should be lowercased and a valid XML and SQL identifier.
title string - n/a The title is a label text that should be displayed in the UI when viewing this object.
Note that this may also be a language token, which is to be translated to the selected language.
charset string - n/a The preferred charset to use when creating database objects and communicating with the database. The charset may only be set upon creation of the database. If you decide to use an existing database, please note, that the charset, which is actually used, might be another.
datasource string - n/a The interpretation of the data source attribute depends on the implementation. For the Yana Framework it is a named data source. You may set up named database connections via the administration panel.
readonly bool - no You may set the database to be read-only to prevent any changes to it. Use this if you wish to create a database viewer, or CD-ROM application.
Description

A root element that specifies important properties and/or requirements. These may be used if the database is created via script, or if by a database client, opens a connection.

Implementation

The charset is to be set during creation of the database. Typical charsets are: utf-8, ascii, iso-8859-1. Note that some DBMS have different writings of the same charset, or may support charsets that other DBMS won't. The implementation must provide a list of valid charsets and automatically convert them to the correct writing for the target DBMS. The implementation must provide a list of valid charsets and automatically convert them to the correct writing for the target DBMS.
The data source in general it is an identifier for a particular set of connection parameters to a specific database. his may either be a JNDI data source for Java, an ODBC data source for C#, or any other named data source for any other language.

Presentation

When displaying an user interface (UI) for a database, the implementation may choose to display the database title attribute as a header.

Element Description

  ELEMENT description (#PCDATA)
  
Description

The description serves two purposes: 1st is offline documentation 2nd is online documentation.
A description is always optional. Note that this may also be a language token, which is to be translated to the selected language.

Presentation

The form generator may use the description to provide context-sensitive help or additional information (depending on it's implementation) on a automatically generated database application.

Element Include

  ELEMENT include (#PCDATA)
  
Description

Database definitions may be split in several files and recursively included. E.g. this may be necessary if you wish to create a reference to another table, which was defined elsewhere.

The list of includes may contain either filenames, or identifiers, which can be converted to filenames by the application.
Note that you should only include database definitions that use the same data source.

Implementation

The child nodes of the database tags of the included files should be included in order of appearance to the database node of the source file. The database nodes themselves are to be ignored. If the included file includes further files, then these should be handled recursively. If a file is listed multiple times, the file must be included only once. If a file recursively includes another, which has already been loaded, the file must be skipped and not be loaded twice. Included files are not allowed to redefine already existing objects. For example, an included file may not overwrite a table definition in the source file. If an already existing element is found, an error must be thrown.

Element Sequence

  ELEMENT sequence (description?)
  ATTRIBUTE
       name        string
       start       integer
       increment   string
       min         integer
       max         integer
       cycle       bool
    
Attributes
Attributes Type Mandatory Default Description
name string yes n/a An unique name that identifies this sequence. It should be lowercased and a valid XML and SQL identifier.
start integer - n/a A sequence always starts with an initial value. The value defaults to the minimal value for ascending sequences and to the maximal value for descending sequences.
Note: the start value must lay within range of the minimal and maximal sequence number.
increment string - 1 An increment value (or step width) specifies the number that is added to the sequence when calculating the successor of it's current value.
min integer - n/a The minimal value is a lower boundary for a sequence. All sequence values must be larger or equal the minimal value. The minimal value may not be larger than the maximal value. The default is 1 for ascending and PHP_INT_MIN for descending sequences.
max integer - n/a The maximum value is an upper boundary for a sequence. All sequence values must be smaller or equal the maximum value. The maximum value may not be smaller or equal the minimum value. The default is PHP_INT_MAX for ascending and -1 for descending sequences.
cycle bool - no If a sequence is a number cycle and the value of the sequence reaches an upper- or lower boundary, it will be reset to the minimum value for an ascending sequence or the maximum value for a descending sequence.
Description

Sequences are integer values, combined with a successor function. They serve various purposes. Usually they are used to auto-generate unique id's.
Note that there are implicit and explicit sequences. For example, an implicit sequence is created when you create an auto-increment column. You must not specify implicit sequences, as these are created and maintained by the DBMS itself.
Also note that some DBMS interpret the integer 0 to be equal to NULL. Thus you are encouraged NOT to create sequences that may contain the value 0 at any time. In addition, some applications may reserve index 0 for default values (e.g. as in data-warehousing).

Implementation

While sequences are part of the SQL-2003 standard, they are not widely supported by most vendors. Except for PostgreSQL, where they are well known feature. They may be simulated for other DBMS though.

Element Initialization

  ELEMENT initialization (#PCDATA)
  ATTRIBUTE
       dbms        string
  
Attributes
Attributes Type Mandatory Default Description
dbms string - generic The name of the target DBMS. The value "generic" means that the definition is suitable for any DBMS. Usually this is used as a fall-back option for DBMS you haven't thought of when creating the database structure or for those that simply doesn't have the feature in question.
Description

Initializing SQL statements, which are carried out right after the database structure has been published on a database. The syntax may either be portable or DBMS-specific.

Implementation

The following values are suggested for the DBMS-attribute: 'generic', 'db2', 'dbase', 'frontbase', 'informix', 'interbase', 'msaccess', 'mssql', 'mysql', 'oracle', 'postgresql', 'sybase', 'sqlite'.

Author: Thomas Meyer, www.yanaframework.net