=pod

=encoding utf8

=head1 NAME

Muldis::D::Core::Routines_Catalog -
Muldis D data definition routines

=head1 VERSION

This document is Muldis::D::Core::Routines_Catalog version 0.1.0.

=head1 PREFACE

This document is part of the Muldis D language specification, whose root
document is L<Muldis::D>; you should read that root document before
you read this one, which provides subservient details.  Moreover, you
should read the L<Muldis::D::Core> document before this current
document, as that forms its own tree beneath a root document branch.

=head1 DESCRIPTION

This document contains one or more sections that were moved here from
L<Muldis::D::Core> so that that other document would not be too large.

These core routines are more special-purpose in nature and are intended for
use in working with the system catalog.  Generally speaking they comprise
the system-defined data definition routines of Muldis D.  These procedures
are mainly for making bootloaders work, since those can not directly invoke
variables such as the catalogs in order to insert into them.

Note that these routines are far from exhaustive as far as providing the
means to do data definition.  The most exhaustive means to do data
definition is to use ordinary data manipulation routines directly on the
system catalog.

=head1 FUNCTIONS FOR SIMPLE GENERIC SCALAR TYPES

=item C<function sys.std.Core.Cat.Order_reverse result Cat.Order params {
topic(Cat.Order) }>

This function results in the reverse value of its argument; a
C<Cat.Order:increase> or C<Cat.Order:decrease> argument results in the
other one of the two; an C<Cat.Order:same> argument results in itself.

=item C<function sys.std.Core.Cat.Order_reduction result Cat.Order params {
topic(array_of.Cat.Order) }>

This function results in the lowest-indexed of its N input element values
that isn't equal to C<Cat.Order:same>, if there is such an input value, and
otherwise it results in C<Cat.Order:same>.  It is a reduction operator that
recursively takes each consecutive pair of input values, for each pair
picking the lower-indexed one if that isn't equal to C<Cat.Order:same> and
otherwise picking the higher-indexed one (a process which is associative),
until just one is left, which is the result.  If C<topic> has zero values,
then C<Order_reduction> results in C<Cat.Order:same>, which is the identity
value for this operation.  The purpose of this function is to provide a
canonical terse way to chain invocations of multiple C<order_determination>
functions to derive a larger such function, such as when you want to define
an C<order_determination> function for a tuple type, which would then be
your control for sorting a relation as per a SQL "ORDER BY" or "RANK".

=head1 PROCEDURES FOR DEFINING DEPOT MOUNTS

=over

=item C<procedure sys.std.Core.Cat.create_depot_mount update {} read {
name(Cat.Name), comment(Cat.Comment)?, is_temporary(Bool)?,
create_on_mount(Bool)?, delete_on_unmount(Bool)?, we_may_update(Bool)?,
details(Cat.ScaLitExprNodeSet)? }>

This procedure is an abstraction over inserting a tuple into the catalog
relvar C<mnt.cat.mounts>.  It will create a new depot mount in the DBMS
whose name is given by the C<name> argument and whose other mount control
details match the other arguments; the mount may be for either an existing
depot or for a newly created one.  This procedure is analagous to a SQL
CONNECT statement or SQLite ATTACH statement.

=item C<procedure sys.std.Core.Cat.drop_depot_mount update {} read {
name(Cat.Name) }>

This procedure is an abstraction over deleting a tuple from the catalog
relvar C<mnt.cat.mounts>.  It will drop an existing depot mount from the
DBMS whose name is given by the argument; the depot behind the mount may
then either cease to exist or persist on.  This procedure is analagous to a
SQL DISCONNECT statement or SQLite DETACH statement.

=item C<procedure sys.std.Core.Cat.alter_depot_mount_so_we_may_not_update
update {} read { name(Cat.Name) }>

This procedure is an abstraction over updating a tuple of the catalog
relvar C<mnt.cat.mounts> such that its C<we_may_update> attribute is made
C<Bool:false>.

=back

=head1 PROCEDURES FOR DEFINING IN-DEPOT NAMESPACES

=over

=item C<procedure sys.std.Core.Cat.create_subdepot update {} read {
depot(Cat.Name), parent(Cat.DeclNameChain)?, name(Cat.Name),
comment(Cat.Comment)? }>

This procedure is an abstraction over inserting a tuple into the catalog
relvar C<fed.cat.mounts{name=$depot}.depot.subdepots>.  It will create a
new subdepot, in the depot mounted under the name given by the C<depot>
argument, whose name and other details match the other arguments.  This
procedure is analagous to a SQL CREATE SCHEMA statement.

=item C<procedure sys.std.Core.Cat.drop_subdepot update {} read {
depot(Cat.Name), parent(Cat.DeclNameChain)?, name(Cat.Name) }>

This procedure is an abstraction over deleting a tuple from the catalog
relvar C<fed.cat.mounts{name=$depot}.depot.subdepots>.  It will drop an
existing subdepot.  This procedure is analagous to a SQL DROP SCHEMA
statement.

=item C<procedure sys.std.Core.Cat.create_package update {} read {
depot(Cat.Name), parent(Cat.DeclNameChain)?, name(Cat.Name),
comment(Cat.Comment)?, package(Cat.Package)? }>

This procedure is an abstraction over inserting a tuple into the catalog
relvar C<fed.cat.mounts{name=$depot}.depot.packages>.  It will create a
new package, in the depot mounted under the name given by the C<depot>
argument, whose name and other details match the other arguments.  This
procedure is analagous to an Oracle CREATE PACKAGE statement.

=item C<procedure sys.std.Core.Cat.drop_package update {} read {
depot(Cat.Name), parent(Cat.DeclNameChain)?, name(Cat.Name) }>

This procedure is an abstraction over deleting a tuple from the catalog
relvar C<fed.cat.mounts{name=$depot}.depot.packages>.  It will drop an
existing package.  This procedure is analagous to an Oracle DROP PACKAGE
statement.

=back

=head1 PROCEDURES FOR DEFINING ROUTINES

=over

=item C<procedure
sys.std.Core.Cat.create_depot_(function|updater|procedure) update {} read {
depot(Cat.Name), parent(Cat.DeclNameChain)?, name(Cat.Name),
comment(Cat.Comment)?, head(Cat.(Func|Upd|Proc)Head),
body(Cat.(Func|Upd|Proc)Body) }>

This procedure is an abstraction over inserting a tuple into the catalog
relvar C<fed.cat.mounts{name=$depot}.depot.(function|updater|procedure)s>.
It will create a new function|updater|procedure, in the depot mounted under
the name given by the C<depot> argument, whose name and other details match
the other arguments.  This procedure is analagous to a SQL CREATE
FUNCTION|PROCEDURE statement.

=item C<procedure sys.std.Core.Cat.drop_depot_(function|updater|procedure)
update {} read { depot(Cat.Name), parent(Cat.DeclNameChain)?,
name(Cat.Name) }>

This procedure is an abstraction over deleting a tuple from the catalog
relvar C<fed.cat.mounts{name=$depot}.depot.(function|updater|procedure)s>.
It will drop an existing depot function|updater|procedure.  This procedure
is analagous to a SQL DROP FUNCTION|PROCEDURE statement.

=item C<procedure
sys.std.Core.Cat.create_package_(function|updater|procedure) update {} read
{ depot(Cat.Name), subdepot(Cat.DeclNameChain)?, package(Cat.Name),
name(Cat.Name), comment(Cat.Comment)?, is_public(Bool)?,
head(Cat.(Func|Upd|Proc)Head), body(Cat.(Func|Upd|Proc)Body) }>

This procedure is an abstraction over inserting a tuple into the catalog
relvar C<fed.cat.mounts{name=$depot}.depot
.packages{parent=$subdepot,name=$package}.package
.(function|updater|procedure)s>. It will create a new
function|updater|procedure, in the package having the name given by the
C<package> argument, in the depot mounted under the name given by the
C<depot> argument, whose name and other details match the other arguments.

=item C<procedure
sys.std.Core.Cat.drop_package_(function|updater|procedure) update {} read {
depot(Cat.Name), subdepot(Cat.DeclNameChain)?, package(Cat.Name),
name(Cat.Name) }>

This procedure is an abstraction over deleting a tuple from the catalog
relvar C<fed.cat.mounts{name=$depot}.depot
.packages{parent=$subdepot,name=$package}.package
.(function|updater|procedure)s>. It will drop an existing package
function|updater|procedure.

=back

=head1 PROCEDURES FOR DEFINING DATA TYPES

=over

=item C<procedure sys.std.Core.Cat.create_depot_type update {} read {
depot(Cat.Name), parent(Cat.DeclNameChain)?, name(Cat.Name),
comment(Cat.Comment)?, type(Cat.Type) }>

This procedure is an abstraction over inserting a tuple into the catalog
relvar C<fed.cat.mounts{name=$depot}.depot.types>. It will create a new
type, in the depot mounted under the name given by the C<depot> argument,
whose name and other details match the other arguments.  This procedure is
analagous to a SQL CREATE TYPE|DOMAIN statement.

=item C<procedure sys.std.Core.Cat.drop_depot_type update {} read {
depot(Cat.Name), parent(Cat.DeclNameChain)?, name(Cat.Name) }>

This procedure is an abstraction over deleting a tuple from the catalog
relvar C<fed.cat.mounts{name=$depot}.depot.types>. It will drop an existing
depot type.  This procedure is analagous to a SQL DROP TYPE|DOMAIN
statement.

=item C<procedure sys.std.Core.Cat.create_package_type update {} read {
depot(Cat.Name), subdepot(Cat.DeclNameChain)?, package(Cat.Name),
name(Cat.Name), comment(Cat.Comment)?, is_public(Bool)?, type(Cat.Type) }>

This procedure is an abstraction over inserting a tuple into the catalog
relvar C<fed.cat.mounts{name=$depot}.depot
.packages{parent=$subdepot,name=$package}.package.types>.  It will create a
new type, in the package having the name given by the C<package> argument,
in the depot mounted under the name given by the C<depot> argument, whose
name and other details match the other arguments.

=item C<procedure sys.std.Core.Cat.drop_package_type update {} read {
depot(Cat.Name), subdepot(Cat.DeclNameChain)?, package(Cat.Name),
name(Cat.Name) }>

This procedure is an abstraction over deleting a tuple from the catalog
relvar C<fed.cat.mounts{name=$depot}.depot
.packages{parent=$subdepot,name=$package}.package.types>.  It will drop an
existing package type.

=back

=head1 PROCEDURES FOR DEFINING DATABASE RELVARS

I<TODO.>

=head1 PROCEDURES FOR DEFINING DATABASE CONSTRAINTS

I<TODO.>

=head1 SEE ALSO

Go to L<Muldis::D> for the majority of distribution-internal
references, and L<Muldis::D::SeeAlso> for the majority of
distribution-external references.

=head1 AUTHOR

Darren Duncan (C<perl@DarrenDuncan.net>)

=head1 LICENSE AND COPYRIGHT

This file is part of the formal specification of the Muldis D language.

Muldis D is Copyright © 2002-2008, Darren Duncan.

See the LICENSE AND COPYRIGHT of L<Muldis::D> for details.

=head1 TRADEMARK POLICY

The TRADEMARK POLICY in L<Muldis::D> applies to this file too.

=head1 ACKNOWLEDGEMENTS

The ACKNOWLEDGEMENTS in L<Muldis::D> apply to this file too.

=cut