=head1 NAME

SQL::SyntaxModel::XMLSchema - Describe an XML schema suitable for storing SQL::SyntaxModels.

=head1 COPYRIGHT AND LICENSE

This file is part of the SQL::SyntaxModel library (libSQLSM).

SQL::SyntaxModel is Copyright (c) 1999-2003, Darren R. Duncan.  All rights
reserved.  Address comments, suggestions, and bug reports to
B<perl@DarrenDuncan.net>, or visit "http://www.DarrenDuncan.net" for more
information.

SQL::SyntaxModel is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License (GPL) version 2 as published
by the Free Software Foundation (http://www.fsf.org/).  You should have
received a copy of the GPL as part of the SQL::SyntaxModel distribution, in the
file named "LICENSE"; if not, write to the Free Software Foundation, Inc., 59
Temple Place, Suite 330, Boston, MA 02111-1307 USA.

Any versions of SQL::SyntaxModel that you modify and distribute must carry
prominent notices stating that you changed the files and the date of any
changes, in addition to preserving this original copyright notice and other
credits. SQL::SyntaxModel is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
or FITNESS FOR A PARTICULAR PURPOSE.  See the GPL for more details.

Linking SQL::SyntaxModel statically or dynamically with other modules is making
a combined work based on SQL::SyntaxModel.  Thus, the terms and conditions of
the GPL cover the whole combination.

As a special exception, the copyright holders of SQL::SyntaxModel give you
permission to link SQL::SyntaxModel with independent modules that are
interfaces to or implementations of databases, regardless of the license terms
of these independent modules, and to copy and distribute the resulting combined
work under terms of your choice, provided that every copy of the combined work
is accompanied by a complete copy of the source code of SQL::SyntaxModel (the
version of SQL::SyntaxModel used to produce the combined work), being
distributed under the terms of the GPL plus this exception.  An independent
module is a module which is not derived from or based on SQL::SyntaxModel, and
which is fully useable when not linked to SQL::SyntaxModel in any form.

Note that people who make modified versions of SQL::SyntaxModel are not
obligated to grant this special exception for their modified versions; it is
their choice whether to do so.  The GPL gives permission to release a modified
version without this exception; this exception also makes it possible to
release a modified version which carries forward this exception.

While it is by no means required, the copyright holders of SQL::SyntaxModel
would appreciate being informed any time you create a modified version of
SQL::SyntaxModel that you are willing to distribute, because that is a
practical way of suggesting improvements to the standard version.

=head1 DESCRIPTION

All concepts in a SQL::SyntaxModel can be represented by XML, whether it is an
XML DOM or an XML string, which can make XML a suitable format for serializing
SQL::SyntaxModels, even though it may not be the most efficient.  However,
because this would involve storing elements which natively have many-to-many
cardinality (like a relational database) in a medium that only stores up to
one-to-many cardinality (like a tree), we will store the otherwise missing
relationships by having references to 'id' attributes in each XML node by other
attributes in other nodes.  This documentation will attempt to explain the
components of a SQL::SyntaxModel XML document and/or document fragments and how
they relate.  Since SQL::SyntaxModel doesn't actually use XML internally, and
that it is your application (or other third party modules) which would map such
XML to SQL::SyntaxModel objects, you are free to modify this schema to your
liking.

=head1 BRIEF NODE TYPE LIST

These are all of the different types of nodes (tag names) that an XML
SQL::SyntaxModel can have.  They are displayed here in a tree to indicate which
types of nodes can be children of which kinds of nodes.  The top two node
levels shown are mandatory, although each may have zero children, which is an
empty SQL::SyntaxModel.  All nodes from level 3 down have an 'id' attribute
that they can be referred to with; each 'id' is an integer and must be unique
for all nodes of the same node type.  When the diagram below has an 'c="M"' in
a node type, then more than one node of that type can go there; whereas, an
'c="1"' says that only one can go there.  All nodes are optional, and except
for the top two levels, there generally can be any number of each type of
child.   Note that in several cases the same node type can be a child of
itself, recursively; this is indicated with an 'r="Y"'.  Only nodes at level 3
or below can have attributes of any kind.

	<root c="1">
		<type_list c="1">
			<data_type c="M" />
		</type_list>
		<database_list c="1">
			<database c="M">
				<namespace c="M">
					<table c="M">
						<table_col c="M" />
						<table_ind c="M">
							<table_ind_col c="M" />
						</table_ind>
						<trigger c="M">
							<block c="1" r="Y" />
						</trigger>
					</table>
					<view c="M" r="Y">
						<view_col c="M" />
						<view_rowset c="1" r="Y">
							<view_rowset c="M" />
							<view_src c="M">
								<view_src_col c="M" />
							</view_src>
							<view_join c="M">
								<view_join_col c="M" />
							</view_join>
							<view_hierarchy c="1" />
							<view_col_def c="M" r="Y" />
							<view_part_def c="M" r="Y" />
						</view_rowset>
					</view>
					<sequence c="M" />
					<block c="M" r="Y">
						<block_var c="M">
							<view c="1" r="Y" />
						</block_var>
						<block_stmt c="M">
							<block c="1" r="Y" />
							<block_expr c="1" r="Y" />
						</block_stmt>
					</block>
				</namespace>
				<user c="M">
					<privilege c="M" />
				</user>
			</database>
		</database_list>
		<application_list c="1">
			<application c="M">
				<command c="M" r="Y">
					<command_var c="M" />
					<view c="M" r="Y" />
					<block c="M" r="Y" />
				</command>
			</application>
		</application_list>
	</root>

=head1 NODE ATTRIBUTE TYPES

Each SQL::SyntaxModel XML node attribute value is one of 4 types:

=over 4

=item 0

B<scalar> - This is the normal kind of node attribute, and it can contain any
scalar value, such as a string or a number.  Some attributes of this type may
actually be restricted, such as to only valid integer or date or boolean
values, but that is outside the scope of this high level categorization.

=item 0

B<enum> - This is the same as scalar except that the values you can store are 
restricted to an explicit enumerated set of values.  (The next documentation 
section lists the currently known enumerated sets.)

=item 0

B<node_id> - There is exactly one of these per node; it is a number which
uniquely identifies this particular node among all others of the same type. 
Every node in level 3 or below must have one (and the top two levels must not).

=item 0

B<node_ref> - This is a number which is equal to the node_id of another node
that has a particular type; it is used to implement many-to-many relations
between XML nodes.

=back

=head1 ENUMERATED TYPES

These are all of the different enumerated node attribute types that
SQL::SyntaxModel knows about and enforces.

=over 4

=item 0

B<cct_basic_var_type> - scalar record array cursor ref

=item 0

B<cct_basic_data_type> - bin str num bool datetime

=item 0

B<cct_str_enc> - u8 u16 u32 asc ebs

=item 0

B<cct_str_latin_case> - pr uc lc

=item 0

B<cct_datetime_calendar> - abs gre jul chi heb isl jpn

=item 0

B<cct_index_type> - noconstr unique foreign uforeign

=item 0

B<cct_view_type> - object caller cursor inside

=item 0

B<cct_rs_merge_type> - dis all uni int exc min

=item 0

B<cct_rs_join_type> - equal left

=item 0

B<cct_view_part> - where group havin order

=item 0

B<cct_basic_expr_type> - lit var col view sfunc ufunc

=item 0

B<cct_standard_func> - to_str to_num to_int to_bool to_date
not and or xor
eq ne lt gt le ge is_null nvl switch like
add sub mul div divi mod round exp log min max avg
sconcat slength sindex substr srepeat strim spad spadl lc uc
gcount gmin gmax gsum gavg gconcat gevery gany gsome
crowid crownum clevel

=item 0

B<cct_block_type> - pack trig proc func loop cond

=item 0

B<cct_basic_stmt_type> - sproc uproc assig logic

=item 0

B<cct_standard_proc> - 

=item 0

B<cct_command_type> - db_list db_info db_verify db_open db_close db_ping 
db_create db_delete db_clone db_move
user_list user_info user_verify
user_create user_delete user_clone user_update user_grant user_revoke
table_list table_info table_verify
table_create table_delete table_clone table_update
view_list view_info view_verify
view_create view_delete view_clone view_update
block_list block_info block_verify 
block_create block_delete block_clone block_update
rec_fetch rec_verify rec_insert rec_update rec_c_update 
rec_delete rec_replace rec_clone rec_lock rec_unlock
tra_start tra_commit tra_rollback
call_proc call_func

=back

=head1 NODE ATTRIBUTE TYPES

I<This documentation still has to be written.  Meanwhile, see DataDictionary.pod.>

=head1 SEE ALSO

perl(1), SQL::SyntaxModel, SQL::SyntaxModel::DataDictionary, Rosetta,
Rosetta::Framework.

=cut
