NAME
Muldis::D::Core::Routines_Catalog - Muldis D data definition routines
VERSION
This document is Muldis::D::Core::Routines_Catalog version 0.101.0.
PREFACE
This document is part of the Muldis D language specification, whose root document is Muldis::D; you should read that root document before you read this one, which provides subservient details. Moreover, you should read the Muldis::D::Core document before this current document, as that forms its own tree beneath a root document branch.
DESCRIPTION
These core routines are more special-purpose in nature and are intended for use in working with the system catalog.
FUNCTIONS FOR SIMPLE GENERIC SCALAR TYPES
sys.std.Core.Cat.Order.reverse
function sys.std.Core.Cat.Order.reverse (Order <-- $topic : Order)
This function results in the reverse value of its argument; an Order:increase or Order:decrease argument results in the other one of the two; an Order:same argument results in itself.
sys.std.Core.Cat.Order.conditional_reverse
function sys.std.Core.Cat.Order.conditional_reverse (Order <-- $topic : Order, $is_reverse_order : Bool)
This function results in the reverse value of its topic argument as per Order.reverse iff its is_reverse_order argument is Bool:true; otherwise this function simply results in topic itself. This function is intended for use in the definition of order-determination functions where the definer wants to expend the minimal coding effort while supporting the mandatory is_reverse_order parameter; they can just write the fundamental function body once, for the normal ascending algorithm, and pass the result of that algorithm through Order.conditional_reverse.
sys.std.Core.Cat.Order.reduction
function sys.std.Core.Cat.Order.reduction (Order <-- $topic? : array_of.Order)
This function results in the lowest-indexed of its N input element values that isn't equal to Order:same, if there is such an input value, and otherwise it results in 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 Order:same and otherwise picking the higher-indexed one (a process which is associative), until just one is left, which is the result. If topic has zero values, then Order.reduction results in 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 order-determination functions to derive a larger such function, such as when you want to define an 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". Note that this operation is also known as reduction over order or [<=>].
ROUTINES FOR INVOKING ROUTINES
sys.std.Core.Cat.func_invo
function sys.std.Core.Cat.func_invo (Universal <-- $function : FuncRef, $args? : Tuple)
This function results in the result of invoking the other function named in its function argument with arguments supplied by this function's args argument; each attribute name of args is mapped to a parameter name of the invoked function, and the corresponding attribute value is the corresponding argument for the function invocation. This function will fail if the invoked function has any non-optional parameters such that there aren't any corresponding attributes in args, or if there are any attributes in args that don't have corresponding parameters, or if any attribute values aren't of the declared types of the corresponding parameters. The purpose of func_invo is to support invocation of any function whose name or parameters potentially aren't known until runtime; it forms the foundation of all other system-defined functions that want to invoke a function whose name they take as an argument. The args parameter is optional and defaults to the zero-attribute tuple if no explicit argument is given to it.
sys.std.Core.Cat.curried_func
function sys.std.Core.Cat.curried_func (FuncRef <-- $function : FuncRef, $args : Tuple)
This function results in a reference to a new anonymous function which is the result of currying the other function named in its function argument with 0..N arguments supplied by this function's args argument; each attribute name of args is mapped to a parameter name of the curried function, and the corresponding attribute value is the corresponding pre-bound parameter of the curried function. This function will fail if there are any attributes in args that don't have corresponding parameters, or if any attribute values aren't of the declared types of the corresponding parameters. A curried function effectively does not have the parameters of the original function that were pre-bound, and attempts to supply arguments to those on the curried function will fail. Note that the result of a curried_func invocation can be used as input to another one, as there is effectively no difference in their kind. The purpose of curried_func is to support the passing of functions as arguments to invocations of other routines where the passed function wants to use runtime-defined information in the context that invoked routine, without having to pass that information separately as additional routine arguments. Or the purpose of curried_func is just to easily support defining functions as simplified versions of others.
sys.std.Core.Cat.upd_invo
updater sys.std.Core.Cat.upd_invo ($updater : UpdRef, &$upd_args : Tuple, $ro_args? : Tuple)
This update operator has the same purpose and features as sys.std.Core.Cat.func_invo but that it invokes an updater rather than a function; there is no result to deal with, and there are both subject-to-update parameters and read-only parameters of the invoked updater to bind to; they are bound with the attributes of this updater's upd_args and ro_args arguments, respectively. The ro_args parameter is optional and defaults as per the args parameter of func_invo; the upd_args parameter is non-optional because an updater must always be invoked with at least one subject-to-update argument.
These procedures are applicable to use in all kinds of procedures.
sys.std.Core.Cat.proc_invo
procedure sys.std.Core.Cat.proc_invo ($procedure : ProcRef, &$upd_args? : Tuple, $ro_args? : Tuple)
This procedure is the same as sys.std.Core.Cat.upd_invo but that it invokes a procedure (or system-service) rather than an updater, and that upd_args is optional.
ROUTINES FOR WORKING WITH EXCEPTIONS
sys.std.Core.Cat.fail
procedure sys.std.Core.Cat.fail ($topic : Exception)
This procedure will throw the exception given as its argument; this results in the call stack unwinding, and transaction rollbacks, until it is caught.
sys.std.Core.Cat.try_catch
procedure sys.std.Core.Cat.try_catch ($try : ProcRef, &$try_upd_args? : Tuple, $try_ro_args? : Tuple, $catch? : ProcRef, &$catch_upd_args? : Tuple, $catch_ro_args? : Tuple)
This procedure invokes the procedure (or system-service) named in its try argument with arguments supplied by this procedure's try_upd_args and try_ro_args arguments; each attribute name of try_[upd|ro]_args is mapped to a parameter name of the invoked procedure, and the corresponding attribute value is the corresponding argument for the procedure invocation. If the try routine throws an exception, then any state changes it made roll back (but changes made before that don't), and the call stack unwinds to the try_catch itself; then the procedure named by catch is invoked similarly to try was, with corresponding arguments, but with the extra read-only argument topic whose value is an Exception; if the catch routine also throws an exception (such as to say its not handling the thrown one), then that one is not caught and the call stack unwinding plus applicable transaction rollback carries on to the caller of the try_catch. If the try routine succeeds (doesn't throw an exception), then the catch routine is not called. Each of the [try|catch]_[upd|ro]_args parameters is optional and defaults to the zero-attribute tuple if no explicit argument is given to it.
ROUTINES FOR SPECIAL ENTITY REFERENCE DEFAULT VALUES
These routines are defined primarily for use in the definitions of several reference types that are references to routines; each one is an example routines of an appropriate structure such that the reference types can use references to these routines as their default values.
sys.std.Core.Cat.pass_topic
function sys.std.Core.Cat.pass_topic (Bool <-- $topic : Universal)
This value-filter function unconditionally results in Bool:true regardless of the values of its arguments.
sys.std.Core.Cat.map_to_topic
function sys.std.Core.Cat.map_to_topic (Universal <-- $topic : Universal)
This value-map function unconditionally results in its topic argument regardless of the values of its arguments.
sys.std.Core.Cat.reduce_to_v1
function sys.std.Core.Cat.reduce_to_v1 (Universal <-- $v1 : Universal, $v2 : Universal)
This value-reduction function unconditionally results in its v1 argument regardless of the values of its arguments.
sys.std.Core.Cat.noop
procedure sys.std.Core.Cat.noop ()
This procedure has no parameters and doesn't do anything at all.
PROCEDURES FOR BOOTSTRAPPING A MULDIS D PROGRAM OR DATABASE
These procedures comprise a set of commonly useful system-defined data definition routines, which simplify some tasks of manipulating the Muldis D system catalog dbvars. The following procedures can do the following: create|mount and drop|unmount depots, set|clear topic namespaces, create|drop subdepots, create|drop user-defined routines and data types; they can not create or drop relvars.
Procedures For Defining Depot Mounts
sys.std.Core.Cat.create_depot_mount
procedure sys.std.Core.Cat.create_depot_mount ($name : Name, $comment? : Comment, $is_temporary? : Bool, $create_on_mount? : Bool, $delete_on_unmount? : Bool, $we_may_update? : Bool, $details? : OVLScaValExprNodeSet)
This procedure is an abstraction over inserting a tuple into the catalog relvar mnt.cat.mounts. It will create a new depot mount in the DBMS whose name is given by the 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.
sys.std.Core.Cat.drop_depot_mount
procedure sys.std.Core.Cat.drop_depot_mount ($name : Name)
This procedure is an abstraction over deleting a tuple from the catalog relvar 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.
sys.std.Core.Cat.alter_depot_mount_so_we_may_not_update
procedure sys.std.Core.Cat.alter_depot_mount_so_we_may_not_update ($name : Name)
This procedure is an abstraction over updating a tuple of the catalog relvar mnt.cat.mounts such that its we_may_update attribute is made Bool:false.
Procedures For Defining Topic Namespaces
sys.std.Core.Cat.select_topic_namespaces
procedure sys.std.Core.Cat.select_topic_namespaces ($depot? : maybe_of.Name, $subdepot? : maybe_of.DeclNameChain, $comment? : Comment)
This procedure is an abstraction over assigning a new value to the catalog variable tpc.cat; the 3 parameters correspond directly to the attributes of tpc.cat. If all the arguments are omitted, then tpc.cat will have its default value of all-nothing attributes, meaning there are no default namespaces. If subdepot is a Single then depot must be.
Procedures For Defining In-Depot Namespaces
These 2 procedures conceptually have the extra 2 parameters $depot : Name, $parent? : DeclNameChain, whose values are implicitly supplied from tpc.cat.topic_[depot|subdepot] respectively; those 1 or 2 (as applicable) catalog variables must be non-empty as a precondition to invoking the 2 procedures.
sys.std.Core.Cat.create_subdepot
procedure sys.std.Core.Cat.create_subdepot ($name : Name, $comment? : Comment)
This procedure is an abstraction over inserting a tuple into the catalog relvar fed.cat.mounts{name=$depot}.depot.subdepots. It will create a new subdepot, in the depot mounted under the name given by the depot argument, whose name and other details match the other arguments. This procedure is analagous to a SQL CREATE SCHEMA statement or an Oracle CREATE PACKAGE statement.
sys.std.Core.Cat.drop_subdepot
procedure sys.std.Core.Cat.drop_subdepot ($name : Name)
This procedure is an abstraction over deleting a tuple from the catalog relvar fed.cat.mounts{name=$depot}.depot.subdepots. It will drop an existing subdepot. This procedure is analagous to a SQL DROP SCHEMA statement or an Oracle DROP PACKAGE statement.
Procedures For Defining Depot Routines and Data Types
These 14 procedures conceptually have the extra 2 parameters $depot : Name, $subdepot? : DeclNameChain, whose values are implicitly supplied from tpc.cat.topic_[depot|subdepot] respectively; those 1 or 2 (as applicable) catalog variables must be non-empty as a precondition to invoking the 14 procedures.
sys.std.Core.Cat.create_[function|updater|procedure]
procedure sys.std.Core.Cat.create_[function|updater|procedure] ($name : Name, $comment? : Comment, [Function|Updater|Procedure] $material)
This procedure is an abstraction over inserting a tuple into the catalog relvar 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 depot argument, whose name and other details match the other arguments. This procedure is analagous to a SQL CREATE FUNCTION|PROCEDURE statement.
sys.std.Core.Cat.drop_[function|updater|procedure]
procedure sys.std.Core.Cat.drop_[function|updater|procedure] ($name : Name)
This procedure is an abstraction over deleting a tuple from the catalog relvar 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.
sys.std.Core.Cat.create_[scalar|nonscalar|union|subset]_type
procedure sys.std.Core.Cat.create_[scalar|nonscalar|union|subset]_type ($name : Name, $comment? : Comment, [Scalar|Nonscalar|Union|Subset]$material : Type)
This procedure is an abstraction over inserting a tuple into the catalog relvar fed.cat.mounts{name=$depot}.depot.[scalar|nonscalar|union|subset]_types. It will create a new type, in the depot mounted under the name given by the depot argument, whose name and other details match the other arguments. This procedure is analagous to a SQL CREATE TYPE|DOMAIN statement.
sys.std.Core.Cat.drop_[scalar|nonscalar|union|subset]_type
procedure sys.std.Core.Cat.drop_[scalar|nonscalar|union|subset]_type ($name : Name)
This procedure is an abstraction over deleting a tuple from the catalog relvar fed.cat.mounts{name=$depot}.depot.[scalar|nonscalar|union|subset]_types. It will drop an existing depot type. This procedure is analagous to a SQL DROP TYPE|DOMAIN statement.
SEE ALSO
Go to Muldis::D for the majority of distribution-internal references, and Muldis::D::SeeAlso for the majority of distribution-external references.
AUTHOR
Darren Duncan (darren@DarrenDuncan.net)
LICENSE AND COPYRIGHT
This file is part of the formal specification of the Muldis D language.
Muldis D is Copyright © 2002-2009, Muldis Data Systems, Inc.
See the LICENSE AND COPYRIGHT of Muldis::D for details.
TRADEMARK POLICY
The TRADEMARK POLICY in Muldis::D applies to this file too.
ACKNOWLEDGEMENTS
The ACKNOWLEDGEMENTS in Muldis::D apply to this file too.