Table of ContentsArticle
ELEMENT database (description?, (include | table | view | form | function | sequence | initialization)*, changelog?) ATTRIBUTE name string title string charset string datasource string readonly bool
| 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. |
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.
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.
When displaying an user interface (UI) for a database, the implementation may choose to display the database title attribute as a header.
ELEMENT description (#PCDATA)
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.
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 (#PCDATA)
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.
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 (description?) ATTRIBUTE name string start integer increment string min integer max integer cycle bool
| 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. |
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).
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 (#PCDATA) ATTRIBUTE dbms string
| 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. |
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.
The following values are suggested for the DBMS-attribute: 'generic', 'db2', 'dbase', 'frontbase', 'informix', 'interbase', 'msaccess', 'mssql', 'mysql', 'oracle', 'postgresql', 'sybase', 'sqlite'.
Thomas Meyer, www.yanaframework.net
Definitions