<pre> include_once('adodb.inc.php');<br><fontcolor="#006600"># First create a normal connection</font><br> $db->NewADOConnection('mysql');<br> $db->Connect(...);<br><br><font
color="#006600"># Then create a data dictionary object, using this connection</font><br> $dict = <strong>NewDataDictionary</strong>($db);<br><br><font
color="#006600"># We have a portable declarative data dictionary format in ADOdb, similar to SQL.<br> # Field types use 1 character codes, and fields are separated by commas.<br> # The following example creates three fields: "col1", "col2" and "col3":</font><br> $flds = " <br><font
<pre> RETURNS: an array of strings, the sql to be executed, or false<br> $tabname: name of table<br> $fldarray: string (or array) containing field info<br> $taboptarray: array containing table options<br></pre>
<p>The new format of $fldarray uses a free text format, where each
field is comma-delimited.
The first token for each field is the field name, followed by the type
<pre> C: varchar<br> X: Largest varchar size <br> XL: For Oracle, returns CLOB, otherwise same as 'X' above<br><br> C2: Multibyte varchar<br> X2: Multibyte varchar (largest size)<br><br> B: BLOB (binary large object)<br><br> D: Date (some databases do not support this, and we return a datetime type)<br> T: Datetime or Timestamp<br> L: Integer field suitable for storing booleans (0 or 1)<br> I: Integer (mapped to I4)<br> I1: 1-byte integer<br> I2: 2-byte integer<br> I4: 4-byte integer<br> I8: 8-byte integer<br> F: Floating point number<br> N: Numeric or decimal number<br></pre>
<p>The $colsize field represents the size of the field. If a decimal
number is used, then it is assumed that the number following the dot is
the precision, so 6.2 means a number of size 6 digits and 2 decimal
places. It is recommended that the default for number types be
represented as a string to avoid any rounding errors.</p>
<pre> AUTO For autoincrement number. Emulated with triggers if not available.<br> Sets NOTNULL also.<br> AUTOINCREMENT Same as auto.<br> KEY Primary key field. Sets NOTNULL also. Compound keys are supported.<br> PRIMARY Same as KEY.<br> DEF Synonym for DEFAULT for lazy typists.<br> DEFAULT The default value. Character strings are auto-quoted unless<br> the string begins and ends with spaces, eg ' SYSDATE '.<br> NOTNULL If field is not null.<br> DEFDATE Set default value to call function to get today's date.<br> DEFTIMESTAMP Set default to call function to get today's datetime.<br> NOQUOTE Prevents autoquoting of default string values.<br> CONSTRAINTS Additional constraints defined at the end of the field<br> definition.<br></pre>
<p>The Data Dictonary accepts two formats, the older array
<pre> RETURNS: an array of strings, the sql to be executed, or false<br> $idxname: name of index<br> $tabname: name of table<br> $flds: list of fields as a comma delimited string or an array of strings<br> $idxoptarray: array of index creation options<br></pre>
<p>$idxoptarray is similar to $taboptarray in that index specific
information can be embedded in the array. Other options include:</p>
<pre> CLUSTERED Create clustered index (only mssql)<br> BITMAP Create bitmap index (only oci8)<br> UNIQUE Make unique index<br> FULLTEXT Make fulltext index (only mysql)<br> HASH Create hash index (only postgres)<br> DROP Drop legacy index<br></pre>
<pre> RETURNS: 0 if failed, 1 if executed all but with errors, 2 if executed successfully<br> $sqlarray: an array of strings with sql code (no semicolon at the end of string)<br> $contOnError: if true, then continue executing even if error occurs<br></pre>
<p>Executes an array of SQL strings returned by CreateTableSQL or
<p>The easiest way to install AXMLS to download and install any recent
version of the ADOdb database abstraction library. To install AXMLS
manually, simply copy the adodb-xmlschema.inc.php file and the xsl
directory into your adodb directory.</p>
<spanstyle="font-weight: bold;"> Using AXMLS in Your Application</span>
<p>There are two steps involved in using AXMLS in your application:
first, you must create a schema, or XML representation of your
database, and second, you must create the PHP code that will parse and
execute the schema.</p>
<p>Let's begin with a schema that describes a typical, if simplistic
user management table for an application.</p>
<preclass="listing"><pre><?xml version="1.0"?><br><schema version="0.2"><br><br><table name="users"><br><desc>A typical users table for our application.</desc><br><field name="userId" type="I"><br><descr>A unique ID assigned to each user.</descr><br><br><KEY/><br><AUTOINCREMENT/><br></field><br><br><field name="userName" type="C" size="16"><NOTNULL/></field><br><br><br><index name="userName"><br><descr>Put a unique index on the user name</descr><br><col>userName</col><br><UNIQUE/><br><br></index><br></table><br><br><sql><br><descr>Insert some data into the users table.</descr><br><query>insert into users (userName) values ( 'admin' )</query><br><br><query>insert into users (userName) values ( 'Joe' )</query><br></sql><br></schema><br></pre></pre>
<p>Let's take a detailed look at this schema.</p>
<p>The opening <?xml version="1.0"?> tag is required by XML. The
<schema> tag tells the parser that the enclosed markup defines an
XML schema. The version="0.2" attribute sets <em>the version of the
AXMLS DTD used by the XML schema.</em></p>
<p>All versions of AXMLS prior to version 1.0 have a schema version of
<p>Next we define one or more tables. A table consists of a fields (and
other objects) enclosed by <table> tags. The name="" attribute
specifies the name of the table that will be created in the database.</p>
<preclass="listing"><pre><table name="users"><br><br><desc>A typical users table for our application.</desc><br><field name="userId" type="I"><br><br><descr>A unique ID assigned to each user.</descr><br><KEY/><br><AUTOINCREMENT/><br></field><br><br><field name="userName" type="C" size="16"><NOTNULL/></field><br><br><br></table><br></pre></pre>
<p>This table is called "users" and has a description and two fields.
The description is optional, and is currently only for your own
information; it is not applied to the database.</p>
<p>The first <field> tag will create a field named "userId" of
type "I", or integer. (See the ADOdb Data Dictionary documentation for
a list of valid types.) This <field> tag encloses two special
field options: <KEY/>, which specifies this field as a primary
key, and <AUTOINCREMENT/>, which specifies that the database
engine should automatically fill this field with the next available
value when a new row is inserted.</p>
<p>The second <field> tag will create a field named "userName" of
type "C", or character, and of length 16 characters. The
<NOTNULL/> option specifies that this field does not allow NULLs.</p>
<p>There are two ways to add indexes to a table. The simplest is to
mark a field with the <KEY/> option as described above; a primary
key is a unique index. The second and more powerful method uses the
<index> tags.</p>
<preclass="listing"><pre><table name="users"><br> ...<br><br><index name="userName"><br><descr>Put a unique index on the user name</descr><br><col>userName</col><br><br><UNIQUE/><br></index><br><br></table><br></pre></pre>
<p>The <index> tag specifies that an index should be created on
the enclosing table. The name="" attribute provides the name of the
index that will be created in the database. The description, as above,
is for your information only. The <col> tags list each column
that will be included in the index. Finally, the <UNIQUE/> tag
specifies that this will be created as a unique index.</p>
<p>Finally, AXMLS allows you to include arbitrary SQL that will be
applied to the database when the schema is executed.</p>
<preclass="listing"><pre><sql><br><descr>Insert some data into the users table.</descr><br><query>insert into users (userName) values ( 'admin' )</query><br><br><query>insert into users (userName) values ( 'Joe' )</query><br></sql><br></pre></pre>
<p>The <sql> tag encloses any number of SQL queries that you
define for your own use.</p>
<p>Now that we've defined an XML schema, you need to know how to apply
it to your database. Here's a simple PHP script that shows how to load
the schema.</p>
<preclass="listing"><pre><?PHP<br>/* You must tell the script where to find the ADOdb and<br> * the AXMLS libraries.<br> */<br>require( "path_to_adodb/adodb.inc.php");<br>require( "path_to_adodb/adodb-xmlschema.inc.php" );<br><br>/* Configuration information. Define the schema filename,<br> * RDBMS platform (see the ADODB documentation for valid<br> * platform names), and database connection information here.<br> */<br>$schemaFile = 'example.xml';<br>$platform = 'mysql';<br>$dbHost = 'localhost';<br>$dbName = 'database';<br>$dbUser = 'username';<br>$dbPassword = 'password';<br><br>/* Start by creating a normal ADODB connection.<br> */<br>$db = ADONewConnection( $platform );<br>$db->Connect( $dbHost, $dbUser, $dbPassword, $dbName );<br><br>/* Use the database connection to create a new adoSchema object.<br> */<br>$schema = new adoSchema( $db );<br><br>/* Call ParseSchema() to build SQL from the XML schema file.<br> * Then call ExecuteSchema() to apply the resulting SQL to <br> * the database.<br> */<br>$sql = $schema->ParseSchema( $schemaFile );<br>$result = $schema->ExecuteSchema();<br>?><br></pre></pre>
<p>Let's look at each part of the example in turn. After you manually
create the database, there are three steps required to load (or
upgrade) your schema.</p>
<p>First, create a normal ADOdb connection. The variables and values
here should be those required to connect to your database.</p>
