__________________________________________________
Copyright 2003 - 2023 John E. Ragan

This is a legally copyrighted work,
so none of it can,
legally or honorably,
be copied, used, or claimed by anyone other than the owner.
__________________________________________________

__________________________________________________

Operation Manual page 1

Click   HERE   for page 2

          HERE   for page 3

  HERE   for the
Table Of Contents,
Lexicon, and Syntax Reference;

Or {Alt Left Arrow} to return to prior location.
__________________________________________________

Address: jragan.com/axledoc_1.htm#01.00.00
-- . --

Documentation Approximate Statistics

last update	20230919
word-count	nearly a half million *
HTML links	3,459
published bytes	1,905,578

( * See the "Word-Count Analysis" sub-section.)
( Document management is by John Ragan's CoreDoc.)

__________________________________________________

__________________________________________________
Preface To The Operation Manual
__________________________________________________
Address : jragan.com/axledoc_1.htm#01.01.00
-- . --

Please read this preface.

-- . --

Descriptions of 3 similar web pages.
      "Executive Summary"
      An abbreviated and simplified description of AxleBase. It is designed for busy executives and for those who are not technically oriented.
      "Description"
      An expansion and technical enhancement of the executive summary. It may give the best overall description of the system and its abilities.
      "Operation Manual"
      This operation manual is for the managers and technicians who will implement and operate AxleBase. It is documentation for organization managers, database administrators, data administrators, system designers, and software engineers.

AxleBase began life as "Empirical" computer science research. At a time when serious computer jobs were handled entirely by mainframe computers, the author wanted to know how far the lowly desktop computer hardware could be pushed by software engineering. As computer science, it was a decade of fun while his Creator allowed him to do that which was obviously impossible; i.e., the AxleBase project. Work on it stopped in 2015.
      ( Research Findings:   See the "Research" page.)

Surely, he thought, the billionaire software companies have eclipsed AxleBase, and nobody else is interested. Friends and aquaintences disagreed, and arqued that AxleBase is too sophisticated to be outclassed. So it is tentatively being revived by placing this Operation manual on the web site.

Acquisition:
      Mr. Bahani Agalheir and his wife are dear friends, and, for years, he has wanted to sell AxleBase. Bahani is highly educated, hard working, trustworthy, and one of the finest gentlemen and fathers that I have ever known. Since Bahani believes that he can find somebody who needs AxleBase, it is for sale.

To discuss acquisition of the AxleBase technology, please contact
      Mr. Bahani Agalhier
      bahani.agalheir@gmail.com
      501-366-3383

Description:
      This Operation Manual is designed for professional database administrators with years of experience, so it is rather technical.
      Whether or not you are technical, it is suggested that you read the "Description" document before this one. It too is technical, but far gentler than this document. It describes what the system can do instead of how to run it.

Manual Update:
      This manual has never been edited, so it is being updated and edited in 2023. The builder wrote various portions as stream of consciousness while building. With over a hundred thousand words, it is being divided into several documents to be more manageable.

System Coverage:
      The AxleBase system is extensive and sophisticated, and can do things never before imagined. After being away from it for years, reading about this technology has been fun for its creator.

John Ragan
AxleBase Builder

-- . --

End of the Preface.

Click here to go to the document contents.

Or press {Alt Left Arrow} to return to previous text.

-- . --

End of the Table Of Contents.

__________________________________________________
Chapter 1
Introduction
__________________________________________________

Address : jragan.com/axledoc_1.htm#10.00.00
-- . --

_________________________

The Instance
a section of
Introduction




Address : jragan.com/axledoc_1.htm#10.10.01
-- . --

You will encounter many references to "instance" as you read. The instance is an instance of AxleBase that is loaded and running in the computer's RAM. The instance is actually the entire AxleBase object that is loaded and functioning in the computer's RAM.

As such, a computer can have many instances working. An extended working object can consist of many instances on many computers scattered across a continent.

But relax because, although that instance object is usually important, it can sometimes become a nebulous transient object. A computer/system user may never encounter a need for using the instance, but a system builder must be familiar with it.

If you are unfamiliar with the concept, you might find it helpful to look at the "AlterInstance" command in the "Manager" object. That might give you a feel for it.

-- . --

End of the Instance section.

Click here to go to the document contents.

Or press {Alt Left Arrow} to return to previous text.

_________________________

General
a section of
Introduction



Address : jragan.com/axledoc_1.htm#10.10.00
-- . --

|-------------------|

Description
a sub-section of
Introduction



Address : jragan.com/axledoc_1.htm#10.10.05
-- . --

The primary objective of AxleBase is the management of inconceivably large data stores. See the "Design Limits" page. He can manage the usual small or mid-sized databases (He has managed his builder's personal data tables for many years), but he has the muscle for large loads. He contains special mechanisms that give him the ability to handle unbelievably "Large" data tables.

AxleBase is a complete "Relational" database manager. When completed, it was probably, and may still be, the world's most powerful. He is sometimes also described as a database engine because he was designed to be compiled into other software projects.

AxleBase does not just claim to be embeddable. He was built for that purpose so that he lives and functions entirely within a host system. He is a DLL component that is invisible and that a system engineer can compile into a product. After he installs the DLL on the computer, when the software engineer declares the AxleBase object in his code, all of the AxleBase interfaces, commands, objects, error handlers, etc. are immediately available within his project.

The host will use industry standard ANSI-92 SQL(Structured Query Language) to control him. He has SQL enhancements to handle very "Large" objects, but they do not interfere with standard "SQL", and when a deviation is made from the ANSI-92 standard, the deviation is openly and explicitly stated in this document. (Some basic SQL usage is presented in sub-sections following the "ExecuteSQL" sub-section.)

He provides selectable universal "Interfaces" that offer specialized services, such as the security-hardened "SysLink" communication interface that is built around the "SysLink" communication protocol. All of them are designed to be the link into any production system. That and his light weight make him easily deployable.

A secondary objective is cost reduction. Instead of paying for a super-computer or mainframe to handle very large databases, he is designed with the ability to do it on low cost desktop computers; thereby bringing giant data tables wherever they may be needed.

-- . --

End of the Description sub-section.

Click here to go to the document contents.

Or press {Alt Left Arrow} to return to previous text.

|-------------------|

Documentation Characterization
a sub-section of
Introduction



Address : jragan.com/axledoc_1.htm#10.10.10
-- . --

Intended Audience :
      All personnel.

AxleBase is designed for the performance of :
      Very Large,
      Unusual,
      Delicate, and
      Complex tasks.

Its documentation must serve disparate professional groups including :
      Managers,
      Software Engineers,
      Database Implementers,
      System Administrators, ( "DBA"s),
      End Users.

Which is why the documentation is large and expanding. There are sections that address one of those tasks for one of those groups, and there are sections that are needed for all tasks for all groups.

( The builder was forced to reenter the code for months in 2022 to complete the unfinished "ShareDatabase" utility.
      For one in whom the Creator placed a love for logic, relearning the internal beauty of AxleBase has been tremendously enjoyable.)

The documentation attempts to assist the manager in planning for the acquisition and implementation of AxleBase and for the allocation of manpower and other resources.

Software engineers will find that AxleBase can be viewed as a programming language, which allows them to embed it in their systems and languages; that allows them to create systems that drive a powerful database manager as a tool for manipulating databases. The engineers know that a "DBA" probably should work with them.

The implementers are those who design and create databases, tables, jobs, and security protocols in those databases.

The DBA monitors performance, monitors system health, and performs daily administration, such as unattended system operation, security, and hardware load. Frequently, the DBA is also the implementer since he performs the never-ending job of database administration.
      Depending upon the size and complexity of the database administration, its hours of availability, and the importance and cost of the data, the business managers may even decide that a DBA group is needed for its administration.
      Depending upon how AxleBase is used, the end user may not have enough technical training or experience. In that case, the DBA may be tasked with user training and support. For example a common use of a database is routine queries of the data tables, which may not be as easy as it is for ordinary database managers.
( Warning :
      See the table "Lock" warning in the "SQL Select" sub-section. )

( For Software Engineers:
      In addition to this documentation, AxleBase contains internal documentation that was specifically designed for system engineers.
      The Seeper app was intended to translate apps from one language into another, and was abandoned when AxleBase development ceased. At that point, it could partially translate, and completely report on the target's internal characteristics.
      The Seeper app reports 259,437 words in the comments inside AxleBase, making it even greater than this documention. Last run 20221203.)

Advanced System Tutorials:
      The advanced features at the end of this documentation have extensive comments that cover operation and theory tutorials; i.e., such things as very large distributed table and system design and operation, and error management for such tables and systems.

-- . --

End of the Documentation Characterization.

Click here to go to the document contents.

Or press {Alt Left Arrow} to return to previous text.

|-------------------|

Documentation
Word-Count Analysis
a sub-section of
Introduction Section



Address : jragan.com/axledoc_1.htm#10.10.11

Initial upload 20221208
Last update 20230310
-- . --

Intended Audience :
      Organization Managers,
      Software Engineers.

Documentation Word-Count

Location	count
operation manual page 1	57,910
operation manual page 2	45,123
operation manual page 3	71,855
total operation manual	201,620
technical description page	13,609
embedded documentation  *	259,437
grand total	474,666

Word counts exclude special characters and HTML code.

-- . --
For Managers And System Engineers

( * Embedded in system code.)
      Professional system development includes embedding technical documentation within the programming code as the code is written to support maintenance and alteration by system engineers. Most major organizations require such in-code documentation. Software engineers; i.e., the designers, developers, and programmers, usually refer to it as comments, and will be very interested in seeing these numbers, so the decision was recently (20221205) made to report all of the system's documentation.

Embedded comments are required by the complexity of large systems, which can rival the complexity of biological systems. The complexity is so great in large systems that even the embedded comments become complex. The AxleBase builder decided early in the project that he would comment as extensively as possible. AxleBase is so large and complex that its unseen comments may be more important than this published documentation.

Various systems were built to support the AxleBase project. A system named Seeper, was built to translate a system's code into the C++ language, but was abandoned when AxleBase development ceased. At that point, Seeper could partially translate and report a target system's internal characteristics. The Seeper run on 20221203 reported 259,437 words in internal AxleBase comments.

An Actual Seeper Run and Analysis Of AxleBase

Run Time	0:4:6	h:m:s
Lines Total Start	74,210	not blank
Lines Total End	60,734
Lines Code	53,302	in source
Comments	27,084	in source
Comment word count	259,437
Code Bytes	1,771,502	in source
Bytes Translated	1,546,441	result
Percent Changed	87 %	of source
Classes	17
Forms	0
Modules	2
Functions Global	499	subs & props
Functions Total	908	subs & props
Variables Module	1,127	private and global.
Variables Function	5,185
Arrays Total	599
Loops	1,137
API Calls	0	not translated *

* No windows API calls were used in     AxleBase to insure its portability.

-- . --

End of Documentation Wordcount analysis.

Click here to go to document contents.

Or press {Alt Left Arrow} to return to previous text.

|-------------------|

System Solidity
a sub-section of
Introduction



Address : jragan.com/axledoc_1.htm#10.10.12
-- . --

Intended Audience :
      Managers,
      Software Engineers,
      Database Designers,
      System Administrators, ( "DBA"s),
      End Users.

This subject, which is so important to all of us, cannot be answered definitively. For substantiation of that statement, see the "Incompleteness Theorem" appendix of the "Theory" document. But there can be strong indicators, such as the following.

Experience:
      Starting in the last century, this author designed and coded autonomic systems with complex system-to-system and system-to-people interaction including querying database servers on mainframes, checking hardware, compiling and distributing complex reports, etc. that ran on networks.
      One of them had run fifteen years at last check, performing high-speed mission-critical emergency work-crew dispatching for one of the world's largest corporations with no errors and no down time. It worked so well in its first major emergency, dispatching twenty-five thousand men around the clock for days, that a plan to rewrite it and move it from its little PC to a mainframe was cancelled.

Formal Testing :
      See the "Notable Tests" page for documented and published test results.

Other Trials :
      - Except where incomplete or noted otherwise in its documentation, every one of the hundreds of commands, functions, queries, configurations, etc. was tried multiple times after its coding was completed. If it appeared to be fragile, it was attacked in attempts to break it. It was intentionally run with invalid parameters.
      - High speed looping systems were constructed that ran commands until forced to stop. Their intensity sometimes destroyed disk drives and computers.
      - For five or ten years, the builder's personal system, built around AxleBase, has been used many times nearly every day without detectable errors in AxleBase. (It did, however, continue to point out his incompetence as an administrator for several years. AxleBase has no sense of humor.)

-- . --

End of the System Solidity sub-section.

Click to return to document contents.

Or press {Alt Left Arrow} to return to previous text.

|-------------------|

AxleBase System Security
a sub-section of
Introduction



Address : jragan.com/axledoc_1.htm#10.10.13
-- . --

Intended Audience :
      Primarily management,
      but Software engineers,
      and ( "DBA"s) may be interested.

-- . --

See the "Feasibility Testing In AxleBase" section of the "SysLink Protocol" documentation.
      Since the SysLink protocol is built into AxleBase, the following SysLink sub-sections might also be of interest.
      "Processor Load"
      "System Interfaces"
      "Encryption"
      "Autonomic Systems"

-- . --

See also the 10 sub-sections of the "Security"" section of this AxleBase documentation.
    Sub Sections
      "Introduction"
      "Additional Security"
      "Security Activation"
      "Visibility Of Stops"
      "Canonical Permeability"
      "The Architecture's Impact"
      "Passwords"
      "Granting Access"
      "Step-By-Step Turn On"
      "VPN (Virtual Private Network)"

-- . --

Be alert also for many other security mechanisms scattered through the AxleBase system. For example, see the many configuration settings for the DBA such as the three "Comm Hide Error"" settings that obviate hacker probes.

-- . --

End of the System Security sub-section.

Click to return to document contents.

Or press {Alt Left Arrow} to return to previous text.

|-------------------|

AxleBase System Testing
a sub-section of
Introduction



Address : jragan.com/axledoc_1.htm#10.10.14

updated 20221110
-- . --

Intended Audience :
      Primarily management,
      but Software engineers,
      and ( "DBA"s) may be interested.

The builder has made a concerted effort to find and fix every error and shortcoming in the
            theory,
            design,
            engineering, and
            programming
of the AxleBase system through exhaustive test and trial.

-- Formal Testing --

The "Notable Tests" page presents a number of documented tests with their published results.

Note that the reported times reflect execution on hardware from the last century. Merely replacing the old disk drives with today's solid state storage might increase those speeds by a hundred times. To get a feel for that, mentally move decimal points two places to the left when reading the published test durations

Not all formal tests are shown. For example, this ten or fifteen year-old note was found while editing this document in 2022:
      "A virtual table of trillions of rows was joined to billion-row tables. However, it was decided that since people were having trouble understanding basic AxleBase, and since the big name brands were simply copying tables and calling them virtual, people would certainly be confused by real virtual tables. So virtual table tests were withdrawn. But that was alright with the builder because those petabyte-sized joins were beating the daylights out of equipment that he could not afford to replace."
      See "CreateVirtualTable" in the API chapter, and the various "Virtual Tables" discussions in the "Advanced Topics".

-- Informal Trials --

When a feature, command, or query was completed, it was tried with every invalid parameter that was imagined.

AxleBase has managed my personal database for five or ten years. It is 01:00 in a morning of 2022 as I type this because AxleBase is big and my memory is too small to be a "DBA". I have been looking for years for a bug in my personal system, which uses AxleBase as its embedded database manager. Discovered tonight was that it is not a bug, but one of the many protective system configurations, the "Dataset Size Limit", which an "AxleBase Error Protocol" error message had been telling me for years, but... etc.
      So as of this morning, I can safely write that, as far as I can remember, AxleBase has evinced neither bug nor error nor shortcoming in the past decade of daily use.

-- Mechanized Tests --

As work progressed on AxleBase, it quickly became obvious that its size and complexity required constant testing of everything. Yes, everything. The effort to reduce size and code by reusing code and objects compounded complexity, and routine work began to break things that "had worked before".

Therefore, work stopped to build a testing app, "AxHandle", that became fairly sophisticated in itself. It ran nearly every command and query in AxleBase when a button was pressed, so the button was pressed often.

-- Stress Tests --

Various stress tests were run through the years. The most impressive was when networked computers ran AxleBase "Instances" 24-7 for years building a test table that contained 100 Billion rows. It was spread across 16 computers in 38,005 files on 22 disk drives. It was fun, and delivered impressive SQL queries for local techies. See the "VLT" test report.

It was difficult for the builder to believe that AxleBase could manage the number of files that might be created for very large tables. A stress test was devised, run, and recorded. The operating system had begun to experience problems when the test was stopped, but the AxleBase file management sub-system reported no problems. At that point, the AxleBase file manager was managing 10 million (10,009,096) data files. That number of data files could hold 20 petabytes, or 20,018,192,000,000,000 bytes. See the "File Manager Stress" test report.

-- . --

End of the AxleBase System Testing sub-section.

Click to return to document contents.

Or press {Alt Left Arrow} to return to previous text.

|-------------------|

Support For Mobility
a sub-section of
Introduction



Address : jragan.com/axledoc_1.htm#10.10.15

uploaded 20230503
-- . --

Intended Audience :
      Organization managers, Database Administrators, System Developers, operators.

Purpose :
      The purpose of this sub-section is to describe the various AxleBase abilities and mechanisms that support and protect mobile operations, and that can overcome problems that are inherent in those operations.

      The original purpose of the "SysLink" protocol development was to give AxleBase a secure and controlled autonomy on a public network such as the internet. Therefore, the "SysLink" protocol has been embedded in AxleBase to help with database support for mobile operations, including the fact that high-end database managers usually operate 24-7 as unattended, or autonomous, servers. Accessing that communication interface is discussed in the "SysLink Interface" sub-section and others.

      Serious high-end database managers offer a universal link to any application through the "SQL" language. Any app. can be built to communicate with an AxleBase instance to query an AxleBase database. Any point-and-click interface that translates the user's commands into SQL commands in the background will allow the user to send sophisticated queries to the database without knowing how it happens. Or power users can enter SQL strings. (The writer has built many and varied applications that used SQL links to various brand-name database managers for users who knew neither SQL nor databases.)

      Mobile operations have peculiar needs for database support, but database managers can have features that serve those needs. For example, AxleBase has features specifically designed to provide dependable data support in hostile environments. For example, the DBA can configure settings for each AxleBase database to support mobile users with or without SysLink (although the use of SysLink is recommended).

Dangerous Data Returns

      AxleBase is designed to manage databases of many tables with many exabytes in each table, and he could quickly respond to a query "Joining" some of those tables. Those responsible for the networks being traversed and those sharing them might not respond well to that dataset traversing their infrastructure.

      For safety, the database administrator can set a value in each database's configuration that limits the "Dataset Size" of data returns. If a query exceeds that value, AxleBase will return an error to the user who can then correct his query or use the mechanism described below to incrementally retrieve his massive dataset.

Broken Data Connections

      A broken or noisy connection to a standard database manager requires that the query be resubmitted and rerun, thereby straining expensive resources and users' patience. The DBA can tell AxleBase to automatically handle that problem. See "Cache Returns" in Configurable Attributes.

      If a connection is broken after initiating a query, AxleBase will continue running the query and save the return when finished. He will then continue processing other queries while waiting for the user or his app to reconnect and ask for the saved dataset. If the break occurs after the return begins, AxleBase will save the unretrieved portion of the dataset until it is again requested. (See "Data Retrieval Tools" compendium, and the "the Data Transfer Protection Technology" sub-section.

The return of the dataset will resume until complete or until the connection again breaks. AxleBase is designed to build and return datasets larger than any computer can handle, so such a return can be interrupted and resumed many times. That feature supports many users simultaneously in continuous operation.

      Perhaps that feature will encourage those who investigate networks that may be cut frequently.

Deferred Data Returns

      The mechanism described for broken data connections can be controlled by the user without DBA configuration. If the user has a query that will run a long time, he can specify a "Return Cache" within the query, submit it, turn off his cell phone to take a nap, and reconnect later to get the results.

      This feature can support installations that serve both mobile and fixed station users. The fixed station user will conserve the resources that would otherwise be used by the mobile users' deferred returns.

Mangled Data Returns

      Datasets can be disrupted in transit by undetectable tiny ambience anomalies that might not affect other types of communications. (I isolated and identified this problem in a network of twenty thousand workstations, and a multitude of autonomic processes, that used various big-name database managers.) Therefore, AxleBase allows the user or the user's app to request retransmission of all or specified parts of large datasets. See "Data Retrieval Tools" compendium, and the "the Data Transfer Protection Technology" sub-section.

Data Security

      "Security" is built into serious database managers and access to data can be controlled as tightly as desired. Each database has its own security settings administered by the DBA. (Some of these features are found only in AxleBase.)

      Where an owner is nervous about mobile access to his database, there are features that can impose universal restrictions. Because AxleBase can manage gigantic tables that are too big to be backed up, each database has a switch whereby the DBA can override security with "Deny All DDL" operations to protect tables. Similar switches can override security to "Deny All Data Updates" and "Deny Table Scans" of large tables in each database. (A table scan is a query that performs at least one read that does not use an index, which could run for years against an AxleBase-class table.) (For example, if a computer can read a row every one thousandth of a second, it will take close to 4 months to read the hundred billion row test table in the AxleBase lab.)

      The DBA can turn on ( "Encrypt Outbound") encryption in a database, which will cause all data returns to be encrypted. The user cannot turn that off, but if the DBA is not using that feature, the user can encrypt each query with the "SetVectorEncryption" or the "SetVectorReturnProtocol" options, or he can "Encrypt" each deferred return. That feature is constructed so that an app, also, can add the option to each query.

      If the DBA activates the SysLink interface, then AxleBase will accept and send only SysLink traffic which makes available the floating-key tri-level encryption and authentication for all traffic.

      If the DBA turns on permission security, then access permissions must be "Granted" to individuals and/or groups using the standard CRUD model with AxleBase extensions. Permissions are create, read, update, delete, execute, metadata update, etc. for each table, database, and database domain. Installation domains and databases also have access permissions. Each user must then be assigned access permissions for domains, databases, tables, etc., thereby creating vertical and horizontal security partitions.

      Sensitive data should not be casually exposed to mobile access, but where it is needed, the DBA can activate a hardened "Audit" trail for every data row in the entire database. After activation, that feature's hardness prevents de-activation even by the DBA. Each row in the database carries its own detailed audit data that cannot be accessed, and audit history can be destroyed only by destroying the entire database and its backups. Audit trails are in addition to standard logging by the database manager.

      AxleBase was designed for unusual uses, so the security features administered by the DBA are a longer list than covered here. If the installation is secure, hardware is locked down, database security administered well, and data in transit protected by SysLink, then support for mobile users will be as secure as possible.

Privacy And Anonymity

      The relational database construct simplifies protection of privacy and anonymity that can be left to the professional DBA during his design phase. If told to protect certain data, he will design the database with that sensitive data in separate table(s).

      Since it is a relational database, that sensitive data table(s) can be easily rejoined to other tables in queries as usual, but only by those who have access permission to that sensitive data table as described above.

      The database manager will insure that data inserts go into the correct tables.

      Note: Data is seldom, if ever, entirely unstructured. For example, although not designed to do so, the SMTP protocol automatically structures email for insertion into relational databases (,which certain spy agencies love).

Dependability

      When enabled and configured, multi-level hot table segmented failover for self-healing, with automatic anomaly detection, can be entirely managed by AxleBase throughout multiple catastrophic failures. Resilience of the configuration is limited only by allocated resources, and by the service speed that the DBA is willing to sacrifice. (Configuring for catastrophic failure is covered on the advanced features page.) (Increasing resilience increases the load on AxleBase, which the DBA will evaluate and report.)

Server-Side Mobility

      Some specialized mobile operations, such as the military, that exhibit highly fluid and rapidly changing deployment topologies, also require extremely fast reaction time and high dependability from dedicated local mobile database servers. The size of AxleBase may be part of the solution because the world's most powerful database manager occupies less than a megabyte of space; i.e., so he can be deployed in tiny hardware. (This addresses group operations where speed and deployment topology fluidity substantially exceed those of city traffic, and includes instant catastrophic loss management for multi-node entities, as covered in failover options of the advanced technology page.)

Embedded Interface

      AxleBase has his own interface that is always independent of other apps, including those in which he is embedded. All of the above described features are behind that interface and can be accessed and used only through that interface and only where AxleBase allows it. That means, for example, that AxleBase security is only AxleBase security. Database programmers are familiar with this fact and, using this documentation, give their software hooks into the database manager's interface for control and querying as needed. Containing nearly a half million "Words", the AxleBase documentation tells them how to do such things.

-- . --

End of the Support For Mobility sub-section.

Click to return to document contents.

Or press {Alt Left Arrow} to return to previous text.

|-------------------|

Operator Hints
a sub-section of
Introduction



Address : jragan.com/axledoc_1.htm#10.10.16
-- . --

Intended Audience :
      Operators. Those who will be using AxleBase.

The operation of AxleBase can be difficult. Some commands take many parameters, and a SQL query can be a huge character string. Such clerical tasks can take hours and overwhelm the AxleBase builder. Following are a few techniques that help him.

The AxleBase builder usually uses "AxHandle" to operate AxleBase because AxHandle handles much of the work. For example, when a double click on a database name tells him to open a database, AxHandle automatically loads an AxleBase instance, and runs the "OpenDatabase" command. Then when he is told to run a command, he first opens a "Manager" or "Data Vector" object, whichever is appropriate, and hands the command to the object.

When working with a command that requires a long string such as a long parameter list, or a very long SQl query, the AxleBase builder displays notepad and composes the string in notepad. He usually makes many mistakes, so he corrects the notepad display and copies the update into AxHandle for each attempt.

When working with a command that may load erroneous data or configurations into the database, which could keep the database from opening, he is careful to keep the system running (sometimes all day) until he corrects any errors.

And do not forget AxleBase's test abilities. When the system "Test" toggle is on, or the command carries a "Test" command in an Appendix capsule, the command will run up to the point of commitment and exit. That will allow debugging of the command or query for as long as the operator wishes before commitment.

(You may have noticed that neither the builder, nor AxHandle locked the database before running the command. He could modify the AxHandle app to automatically lock the database before running the command, but he is tired of messing around with the system at the moment.)

-- . --

End of the Operator Hints sub-section.

Click to return to document contents.

Or press {Alt Left Arrow} to return to previous text.

|-------------------|

Design Objectives
a sub-section of
Introduction



Address : jragan.com/axledoc_1.htm#10.10.20
-- . --

Intended Audience :
      Primarily management, but everybody will be interested.

A database manager that can manage
       very "Large" data objects
       on the cheapest equipment available
       as an embedable object.

( * Data tables and control files are designed to be totally visible to their owners; even accessible by text editors.)

( ** If you know how to use a DLL object in a program, then you know how to embed and distribute AxleBase.)

( Although nearly hopeless at this time, even the speed of light was repeatedly addressed as an engineering problem for AxleBase-class systems. For example, see the axsys super-system section's "Domain Space Generation" sub-section.)

-- . --

End of the Design Objectives sub-section.

Click here to go to the document contents.

Or press {Alt Left Arrow} to return to previous text.

|-------------------|

Installation Architectures
a sub-section of
Introduction



Address : jragan.com/axledoc_1.htm#10.10.25
-- . --

Intended Audience :
      Managers,
      Software Engineers,
      Database Designers,
      System Administrators, ( "DBAs").

-- Definition --

As used in this sub-section, installation refers to the physical and geographical location of an AxleBase system, its organizational service limits, and its configuration.
      As such, an installation may be a part of a single desktop computer, or it may be an organization's continent-wide sphere of operation.
      In any case, a particular installation is ultimately defined and created by the organization's task and its organizational managers.

The installation was defined because it points out an unusual characteristic of AxleBase that, if grasped by managers, database designers, and "DBAs", can deliver unexpected benefits; i.e., unlike other database managers, AxleBase was intentionally designed and built with great task-plasticity as you will see below.

-- Enablers --

The AxleBase builder worked assiduously to keep the AxleBase object as small as possible by
      - multi-tasking internal code
      - and using multi-tasked object-based engineering.
      Of some importance to organizational managers is the fact that the AxleBase object, which provides everything covered in this document, is a single executable file smaller than a megabyte. Ergo, the entire advanced AxleBase technology can be deployed on a single very small chip plus data storage.

      - Therefore, an AxleBase file can be a database server, a database client, or both; whichever you need.
      - That allows you to design your system architecture as a central database server that serves clients and other database servers.
      - Or a series of data servers supporting each other.
      - Or a group of data servers that specialize in data or tasks.
      - Or etc...

      - Although more work for the system's "DBA", an extended "Security" mechanism can configure a hardened installation of AxleBase that can be destroyed only by the larger natural or man-made disasters.
      - Or that can be destroyed only by a global event.
      - Or, if you have offworld assets, can be destroyed only by an interplanetary event.

      - Administration of an AxleBase system is assisted by his internal tools, some of which are listed in the "System State Compendium" They include everything from a simple manual one-time check of a table up to around-the-clock autonomous systems that can lock and restore data tables and notify management and the "DBA" team.

      - An AxleBase data object that we call a "table" is designed with definition flexibility that allows the "DBA" to define it as other tables in the local database, or tables in remote databases, or text files, or etc...
      - The "DBA" can even define a table by combining geographically dispersed tables. See the CreateVirtualTable command.

      - AxleBase guarantees data validity by monitoring data objects that service queries before and during queries. When a SQL query is initiated, AxleBase evaluates all data objects and networks that will be used by the query, and monitors their health as the query progresses. AxleBase will not return a dataset if he cannot get all of the data.
      For example, every query of the 100-Billion-row table initiated health checks of that table's 38 thousand dispersed files, and he monitored their health as the query proceeded, but notice how fast each query executed. (Such ancillary activities are included in the run times reported on the "Notable Tests" page.)

      - A security mechanism that could, in theory, make it possible to lose AND recover storage hardware, data tables, and network segments during a query without disruption of the query is the "recrescense" technology that is covered in the "Interrupted Development" sub-section.

      - AxleBase is designed to manage astronomically large tables. If you have one or more tables that fit that description, then the "DBA" can configure the AxleBase "Super-System" for speed. See the "Super-System" section and the dozens of sub-sections that follow it in the "Advanced Topics".
      - AxleBase also contains mechanisms that the query operator can use in his queries to protect computers and networks from damage by very large dataset transits. See the "Data Retrieval Tools Compendium".
      - All of the functions and services that you will read about in this manual are integrated with all of the above abilities, unless stated otherwise. (As you can understand by now, that "unless" qualification is only in case I have forgotten something.)

-- More --

Et etc.... There is more. As you work and study, you will discover other tools and configurations such as the data source "Torrent" handler and the "Dirty Data"-source manager.

The 2015 development shutdown left a few things unfinished. See the following "Interrupted Development" sub-section for a list of uncompleted work.

If they may be needed, see the comments in the "Interrupted Development" sub-section concerning mechanisms for alleviating problems that will be raised by relativistic distances in extraterrestrially-dispersed data management.

-- Additional Coverage --

See the following "Military Systems" sub-section)

-- . --

-- Computer Science Theory --

Among other things, AxleBase development was inspired by the biology sciences. This "Installation" sub-section shows the impact of his computer science research on the builder in 1999. In this case, the impact of "Phenotypic Plasticity" in biological organisms on their genomic development is demonstrated in the inordenately vast configuration reach of the little AxleBase object.
      Brought to mind decades later by this recent publication.
      (*ref. Source: "American Scientist", vol. 110, Mar 2022, pp. 94-101, "Evolution And The Flexible organism" by Prof. David Pfennig)

-- . --

-- Miscellaneous --

The following notes were found years after work stopped.

The AxleBase system is capable of constructing a database that is geographically distributed world-wide, that is dynamically reconfigurable while operating, that can be linked to other databases and unlinked as needed, that can create data tables as needed and on the fly, that can redefine foreign objects as native tables, and many other abilities. The definition of a topological construct with a dynamic visual interface might be valuable for the management and administration of such a database.

-- . --

End of Installation Architectures sub-section.

Click here to go to the document contents.

Or press {Alt Left Arrow} to return to previous text.

|-------------------|

Military Systems
a sub-section of
Introduction



Address : jragan.com/axledoc_1.htm#10.10.30
-- . --

Intended Audience :
      Managers,
      Software Engineers,
      Database Designers,
      System Administrators, ( "DBA"s),
      End Users.

Although AxleBase was not specifically designed for military environments, that was a possibility that was in the mind of the builder as he worked. (See the previous "Installation Architectures" sub-section.) Each AxleBase installation can be designed by the "DBA" for local needs. The speed, responsiveness, and reliability that can be achieved by that installation design were part of the reason for some of the unusual features of AxleBase.
      ( The speed reported on the "Notable Tests" page was delivered on disk drives from the last century. The new solid state storage might make AxleBase a hundred times faster.)

See the "extremely high processing speed" that is addressed in the "Unmanned Vehicles" section of the "SysLink" protocol that handles communication for AxleBase. That and other parts of "SysLink" and AxleBase were designed for emergency and battlefield application.

The military mission requires equipment that can move easily and unobtrusively. The entire sophistication of the AxleBase system is in a single computer file of less than one megabyte. In theory, AxleBase could be deployed with every vehicle and every soldier. (Again, note that the little AxleBase object contains everything to allow you to deploy it as both client and server.)

Note the high speed maleability of the AxleBase "Family" network that allows configuration of AxleBase as an unattended autonomic system. Such a system could provide split-second totally automatic recovery from the loss of even an entire database and its server without interrupting a high speed process. Such responses are supported by his internal 24-7 monitors. That recovery can be repeated until every cluster participant is lost. Although of probable benefit for other applications, that feature was specifically designed for high-speed front line air, sea, and land battlefield conditions.

Since he was designed for high speed processing of very Large" data objects, other AxleBase features may be of benefit at the headquarters level.

-- . --

End of the Military Systems sub-section.

Click here to go to the document contents.

Or press {Alt Left Arrow} to return to previous text.

|-------------------|

Interrupted Development
a sub-section of
Introduction



Address : jragan.com/axledoc_1.htm#10.10.35
-- . --

Intended Audience :
      Managers,
      Software Engineers,
      Database Designers,
      System Administrators, ( "DBA"s),

When the project was shut down, there were objects in development, some being planned, and some being investigated, all of which were terminated. For a list, see the "Unfinished When Project Stopped" on this web site's "Shortcomings" page.

Due to the extreme nature of AxleBase, one that his builder would like to see completed is SQL-controlled table locks. It is not on that page, but see the warning about it in the "SQL Select" sub-section.

Mechanisms for alleviating relativistic impacts on extraterrestrially-dispersed data management were being addressed at project shutdown. On a conceptual level, it was found that the AxleBase architecture was conceptually well positioned to support solutions for relativistic problems. It appeared to be an interesting, fun, and rewarding challenge, but it was discontinued with the shutdown.
      See "relativistic disruption" technology in the "Fault Tolerance" sub-section of the "Description" document. (That sub-section was written while the subject was fresh on the builder's mind, so it may be too positively worded, but it still appears possible.)

The "Fault Tolerant Recrescence" in the "Fault Tolerance" sub-section of this manual is one of the advanced AxleBase security mechanisms. Its objective is recovery of lost storage hardware, data tables, and network segments during a query without disruption of the query. See also the "recrescense" technology in the "Fault Tolerance" sub-section of the "Description" page.
      Coding and some testing had been done, but testing and evaluation of this feature was underway when interrupted by development cessation, so let us consider it experimental at this time. April of 2022.)

-- . --

End of the Interrupted Development sub-section.

Click here to go to the document contents.

Or press {Alt Left Arrow} to return to previous text.

|-------------------|

Programming Interfaces
a sub-section of
Introduction



Address : jragan.com/axledoc_1.htm#10.10.40
-- . --

Intended Audience :
      Primarily system engineers and DBA's, but suggested for everybody.

"Error Protocol" And Functions :
      Everything in AxleBase is a function. If you remember that while you develop your code, it can save you a ton of debugging and troubles. If all of your code expects a return, you will not miss an error message. Regardless of how deeply an error occurs, its report will bubble up to the top of the code. (See the AxleBase Error Protocol, and the ShowErrorList function. Note that the error message is standardized for reading by unattended systems as well as by people.)

Objects :
      Internally, AxleBase is an object based construct. He exposes various interfaces of objects that can be used by the engineer. For example, the two main objects are the "Manager" and the "Vector" which can be instantiated by the GUI when ordered by the operator.

The Vector handles data. Generally speaking, the Vector functions like the biological vector and the math vector, which is why he was given that name. The Manager handles everything else. (I type this seven years after I stopped AxleBase development, so there could be exceptions, but that will not be a problem because the function instructions include which object to use.)

-- . --
Example

As an example, let us look at an abbreviated copy of the instructions function, "Share Database". For those who are unable to build a server to host AxleBase, this command allows a database to be shared across a network after it is created. (Not recommended because of security problems.)

This is the "Share Database" command that the user will enter into your software, which will submit it to AxleBase:
oManagerObject.ShareDatabase DatabasePath , DomainPath [, IndexPath [, LogPath [, SegmentPointerPath [, TempDbPath ]]]]

"TestMode" :
      If the user has a concern about system stability, he can first turn on TestMode. As long as it is on, commands will run up to the commit point and exit without committing. It will allow errors to stop the process and return error messages before the commit point.

Execution :
      He will execute AxleBase to load an "Instance" of AxleBase.
      He will use that instance to create a manager object into which, he will pass the commands. See the "Manager Object Interface Introduction". He will pass the above function and the following functions to the manager object for execution.
      The "OpenDomain" function will open the domain that contains the database.
      The "OpenDatabase" function will open the database that will be shared.
      The "ShareDomain" function will share the database domain.
      He will execute the "ShareDatabase" function.
      He will watch for error returns after each step.

-- . --
End Of Example

-- . --

End of Programming Interface sub-section.

Click here to go to the document contents.

Or press {Alt Left Arrow} to return to previous text.

|-------------------|

Socket Programming
a sub-section of
Introduction



Address : jragan.com/axledoc_1.htm#10.10.50
-- . --

Intended Audience :
      Primarily system engineers.

AxleBase contains socket programming in one of its sub-systems, which used Windows sockets to give AxleBase the ability to communicate with remote systems. You are being informed of this so that you can be prepared for communication problems.

Socket programming, and certainly the Windows socket programming, is fraught with engineering challenges. The worst, in this developer's opinion, was the difficulty of trapping and reporting runtime problems. At no time did this developer feel confident that his socket communication code was as professionally solid as the rest of the code in AxleBase.

However, perhaps that is just the nature of communications, which must deal with a fluid reality. In any case, you have been warned, so that you can build in extra control and caution where communication takes place.

-- . --

End of Sockets sub-section.

Click here to go to the document contents.

Or press {Alt Left Arrow} to return to previous text.

|-------------------|

ODBC Drivers
a sub-section of
Introduction



Address : jragan.com/axledoc_1.htm#10.10.55
-- . --

Intended Audience :
      Primarily system engineers.

ODBC is "Open Database Connectivity". An ODBC driver is a small piece of software that assists with using a database manager. It is not needed by AxleBase, because AxleBase contains the ODBC apparatus.

However, since AxleBase was engineered to the ODBC requirements, the organization is free to create its own ODBC drivers to standardize its own software if it wants. You will find an industry standard ODBC interface waiting inside AxleBase, and documented in this operation manual.

( This sub-section is written quite a few years after the writer left the software engineering environment, so maybe the ODBC technology has been entirely dropped by the industry.)

-- . --

End of the ODBC Drivers sub-section.

Click here to go to the document contents.

Or press {Alt Left Arrow} to return to previous text.

|-------------------|

System Identifiers
a sub-section of
Introduction



Address : jragan.com/axledoc_1.htm#10.10.60
-- . --

Intended Audience :
      All personnel.

( ! The identifiers that are generated are linked ONLY to that which is stated. The systems that I build do not secretly obtain, store, or transmit any information about you or anything that you own! Not because I am good, but simply because the one for whom I work commanded us to not be deceitful with each other.)

-- . --
Version numbers

Version numbers came close to losing their function after the billionaires started playing marketing games with them. Therefore, AxleBase version numbers mainly serve tradition.

The version is always stored in the system. The ShowVersion command will display the system's internal version number.

-- . --
Release Numbers:

Release numbers are the best guide to the current level of development. They are seldom consecutive, but they are always sequential. They are a five digit "Integer".

A new release number is simply and truly the identification of the system that was released to the end user. It may be for a major change or for minor cleanups.

The release number is stored in the product and the "ShowRelease" command will display the system's internal release number.

-- . --
SAM versions:

The storage architecture model (SAM) version should usually be of little or no interest. It is mainly for internal use, but is made public because it can be seen in system files.

The SAM has its own versioning identifier. Each time that the SAM is changed, it is assigned a new identifier that may or may not be the same as the AxleBase version or release number.

-- . --
"SysLink" release:

One of the AxleBase interfaces is an abstracted interface that can be used to simplify the host when it is a database server. The SysLink protocol uses release numbers, and AxleBase stores the SysLink release number that he is currently servicing.

-- . --
system ID numbers:

The system contains the following object and process identifiers that are available to the host through the API.
      Instance ID.
          Temporary for life of the Instance.
          See "ShowInstanceID"
      Vector name.
          Temporary for life of the Vector.
          May be set by operator.
      Domain connection ID.
      Database connection ID.
      Dataset ID.
          Temporary for life of the Dataset.
          See "ShowDatasetAttributes"
      Query ID.
          Same as dataset ID.
          May be set by operator.
      Domain ID.
          See "ShowDomainAttributes"
      Database ID.
          See "ShowDatabaseAttributes"
      Table ID.
          See ShowTableAttributes
      Index ID.
      Report IDs.
      Row IDs in some tables.
      Host computer name.
      Operator name.

There are commands to retrieve handles such as IDs and names. For example, there are approximately 32 "show" commands such as ShowInstanceID, and some reports contain IDs.

The identifiers (IDs) are in addition to names that are assigned to objects by human operators and in addition to version and release numbers. All identifiers are unique. They are generated by AxleBase.

A vector name may be assigned by the host. If a vector name is not assigned by the host, it will be assigned by the system. The vector name is unique when assigned by the system.

Identifiers are stored only for permanent objects such as a database. They are stored only as part of the object's properties. When a transient object dies, such as a connection, its identifier dies. When a permanent object is destroyed, such as a table, its identifier is destroyed.

The great amount of identification is provided because the differences between some of the objects are subtle but important while the system is active. Not only do the identifiers provide control, they can be helpful in debugging.

-- . --

End of the System Identifiers sub-section.

Click to return to document contents.

Or press {Alt Left Arrow} to return to previous text.

|-------------------|

Very Large
a sub-section of
Introduction



Address : jragan.com/axledoc_1.htm#10.10.75
-- . --
^

Intended Audience :
      Everybody.

This advanced technology has been temporarily

moved off line during the documentation editing.

The concept of "very large" has historical precedence in database work. It was first applied to databases as "VLDB" and expanded later to include individual tables as "VLT". The concept has remained the same through the years to mean a larger than ordinary object, but its application has changed as hardware and software changed. That which was a very large table on a mainframe before the PC revolution is now routinely managed in a desktop database manager.

-- . --

End of the Very Large sub-section.

Click here to go to the document contents.

Or press {Alt Left Arrow} to return to previous text.

_________________________

Installing AxleBase
a section of
Introduction



Address : jragan.com/axledoc_1.htm#10.40.00
-- . --

|-------------------|

Development Environment Installation
a sub-section of
Installing AxleBase




Address : jragan.com/axledoc_1.htm#10.40.10
-- . --

AxleBase was developed in Windows 2000. More on this later.

After AxleBase is installed on a computer, it will automatically appear among the tools or components in any development environment that is aware of components on the computer. For example, Visual Basic will show it in the list of components that can be referenced. When a reference is set to it in that kind of environment, the AxleBase commands automatically become available within the development environment as part of the development language.

Method 1

At a glance:
1.   Place the exe pack in a temporary directory.
2.   Run that exe to unpack it.
3.   Run setup.exe to install.
That's all.

Place the current AxleBase package in a temporary directory on your local disk. That package is an executable packed file with an exe extension. It does not need WinZip or any other program. When it is run, it unpacks itself into several files in your temporary directory.

When the package is told to unpack itself, it creates several files, one of which is setup.exe. When setup.exe is run, it installs AxleBase on the computer in the system directory.

Save copies of your package. You may need to roll back to a previous release if an upgrade does not work for you.

After installation, the database manager is available for embedding into your host system. Reference it and code to its interface in your project. When you compile and distribute your system, the referenced database manager will go with it.

This will not uninstall a previously installed release. Use the command in Method 2 to do that.

Method 2

A method that some developers use is to place the DLL where they want it and then manually install it. To do this:
    Relocate the DLL.
    At the DOS prompt,
    run the command regsvr32 [path]\AxleBase.DLL.
    Watch the return to insure installation

That method can be especially useful when upgrading to a new release. To uninstall, run regsvr32 /u [path]\AxleBase.DLL.

A fictitious example:
    regSvr32 /u c:\windows\AxleBase.DLL
    regSvr32 c:\dev\AxleBase.DLL

Method 3

A more complex, method is to use a system call from inside the host system to install it every time that the host system runs. That is the method that is used by "AxHandle", but not by "CoreReader". Every time AxHandle is used, he re-registers his internal database manager. That method works well, but is not recommended because it can lead to confusing problems during system development.

Method 4

If AxleBase was installed and shared by another system on the computer, then it will be available for use by your own system.

If it is uninstalled and upgraded, then systems that use it may need to be upgraded to run the new AxleBase release.

-- . --

End of the Installation sub-section.

Click here to go to the document contents.

Or press {Alt Left Arrow} to return to previous text.

|-------------------|

Production Environment Installation
a sub-section of
Installing AxleBase



Address : jragan.com/axledoc_1.htm#10.40.20
-- . --

Like any component, AxleBase should usually be installed on a production system as part of the installation process of the host system.

What happens after installation is up to the host system. For example, when "CoreReader" starts up, he checks the environment to see if his database exists. If it does not, he gives AxleBase instructions for creating it. The tools for doing all of this are covered later in the documentation.

-- . --

End of the Production Installation sub-section.

Click here to go to the document contents.

Or press {Alt Left Arrow} to return to previous text.

_________________________

GUI Front End
a section of
Introduction



Address: jragan.com/axledoc_1.htm#10.50.00
-- . --

Intended Audience :
      Management and software engineers.

GUI = Graphical User Interface. The GUI is that which is seen on the computer monitor, and any programming that is needed to create and control the GUI.

AxleBase is designed to be embedded in an application, so he has no GUI. His interface is designed for the app in which he is embedded, and the systems with which he must communicate.

The host apps should handle the control and administration of their databases. If a GUI is needed in an emergency, "AxHandle" may be pressed into service as an ad-hoc database administration tool, but that is not his purpose and he is not a production-quality app.

If you need a GUI control for AxleBase, just create one. That is, after all, why AxleBase is embeddable.

-- . --

End of the GUI Front End section.

Click here to go to the document contents.

Or press {Alt Left Arrow} to return to previous text.

_________________________

Getting Started
a section of
Introduction



Address : jragan.com/axledoc_1.htm#10.70.00
-- . --

Unpack and install the system as described in the installation section.

Reference AxleBase in the host system.

Decide how the database(s) should be constructed, used, and maintained.

Write the commands in the host system to tell AxleBase what to do.

-- . --

End of the Getting Started section.

Click here to go to the document contents.

Or press {Alt Left Arrow} to return to previous text.

__________________________________________________
Chapter 2
Test And Demo Software
__________________________________________________


Address : jragan.com/axledoc_1.htm#15.00.00
-- . --

The test software is simple software that is designed to demonstrate and test the AxleBase system.

_________________________
AxHandle ; GUI Test Host
a section of
Test And Demo Software



Address : jragan.com/axledoc_1.htm#15.10.00
-- . --


End of the AxHandle header section.

|-------------------|

Introduction
a sub-section of the
AxHandle section



Address : jragan.com/axledoc_1.htm#15.10.05
-- . --

Intended Audience :
      Everybody.

The primary purpose of AxHandle is routine testing of AxleBase in his development environment. He is also made available for demonstration purposes. AxleBase is embedded in AxHandle.

In this case, the host has a point and click GUI interface for interactive control of AxleBase, but an unattended server can also have an embedded AxleBase.

AxHandle is not intended for production use. His purpose is test and demonstration. A hidden problem is that he may be too powerful. For example he simplifies the quick dropping of a very large database.

The Windows operating system sometimes runs out of handles in intense and long-running tests. If that happens, everything can be restarted to release those handles.

AxHandle is multi-instancing. AxHandle is not multi-threaded and is not multi-tasking.

(See more AxHandle sub-sections folowing this one.)

-- . --

End of the Introduction sub-section.

Click here to go to the document contents.

Or press {Alt Left Arrow} to return to previous text.

|-------------------|

AxHandle Assistance
a sub-section of the
AxHandle section

Address : jragan.com/axledoc_1.htm#15.10.10
-- . --

Intended Audience :
      Everybody.

If you use AxHandle, he tries to help. For example, after you run a select query, he runs the "ShowDatasetAttributes" command to see what happened. If it shows that data is available in a standard return, he runs the ColumnName, ColumnStart, and ColumnWidth commands to build a display header, runs the ReturnDataset command to return formatted data, etc. etc. until he has built a data display. So, although many operations are needed, it will appear that all you need to do is run queries.

That sort of help is provided throughout AxHandle to help as much as possible to save time and trouble for all of us. It also provides an example for other GUI developers to follow if they want.

-- . --

End of the AxHandle Assistance sub-section.

Click to return to document contents.

Or press {Alt Left Arrow} to return to previous text.

|-------------------|

Object Control
a sub-section of the
AxHandle section



Address : jragan.com/axledoc_1.htm#15.10.20
-- . --

AxHandle can use any of the AxleBase interfaces. They are selectable on his configuration panel that can be displayed by pressing the Config button.

The fastest is the standard interface. AxHandle defaults to it the first time that he is run.

The standard interface uses two objects, the "Manager" and the "Vector". They are covered in detail in later sections. For now, just be aware that they exist and that AxHandle tells AxleBase to create them as you need them.

When AxHandle loads, he creates a Manager object for you. You will initialize it by opening a domain and a database. The easiest way to do that is by pressing the demo_db button. When the operation is complete, you will be connected to the new demonstration database.

-- . --

End of the AxleBase Objects sub-section.

Click here to go to the document contents.

Or press {Alt Left Arrow} to return to previous text.

|-------------------|

Passing Commands
a sub-section of the
AxHandle section



Address : jragan.com/axledoc_1.htm#15.10.25
-- . --

All commands are listed in the scrolling windows. The top window lists all of the "Manager" commands and the bottom window lists the commands that are used by the data "Vector".

Each set of commands has a do_it button. To run a command, highlight it and press its do_it button to execute it. For example, select the ShowCopyright command and press the do_it button. The copyright will appear in the return window.

There is a parameter window next to each command window in which a parameter can be typed. When the do_it button is pressed, AxHandle will combine the parameter with the command before passing it to AxleBase.

Example :
        1. Click on the OpenDomain command in the top command window to highlight the command.
        2. Then, enter the domain path in the parameter window.
        3. Press the do_it button.
            AxleBase will open the domain.
        4. Click on the "ShowDomainAttributes" command.
        5. Press the do_it button.
        A list of the domain's attributes will be displayed.

-- . --

End of the Passing Commands sub-section.

Click here to go to the document contents.

Or press {Alt Left Arrow} to return to previous text.

|-------------------|

Returns
a sub-section of the
AxHandle section

Address : jragan.com/axledoc_1.htm#15.10.30
-- . --

Messages, errors, and data returns will appear in the bottom window on the screen.

AxHandle sometimes puts instructions in that window to show how he performed an action. For example, when you tell him to create a new demonstration database, he will list the commands that he used so you can create your own databases.

If AxleBase returns an overwhelmingly large dataset, AxHandle will tell you that the return was too large for the window. When that happens, AxHandle will remind you that there are AxleBase commands that you can use to step through the dataset.

-- . --

End of the Returns sub-section.

Click here to go to the document contents.

Or press {Alt Left Arrow} to return to previous text.

|-------------------|

Help
a sub-section of the
AxHandle section



Address : jragan.com/axledoc_1.htm#15.10.35
-- . --

There are help options for each major operation on the help menu.

The AxleBase command syntax is available from the help menu. Click on help and then click on a topic. It will tell you how to find and display what you need. If you need help only for a specific AxleBase command, display the documentation and double click that command.

( AxHandle uses the same documentation mechanism that is used in the CoreReader and CoreModel family. This is not because it is so great, but simply because Microsoft's was so bad. Since this was done, others have created and offered better documentation tools, but they were simply too late. )

For a minimal amount of help with the SQL language, look in the ExecuteSQL sub-section of the API chapter. The entire syntax is presented for each of the commands. The SQL language is one of the simplest languages in existence, but its use is one of the most complex. If you are not familiar with it, you may want to buy one of the many books on the subject.

Use the CoreReader tool for major assistance with constructing SQL queries. You can use it to query databases just by pointing and clicking on data objects and it will show you the SQL statements that it builds.

( The creation of CoreReader showed others how to create similar tools in the early part of the century, so there are now many fine products on the market. However, aside from their user interfaces, they are no better than CoreReader at what CoreReader does, so you might as well use the original. )

-- . --

End of the Help sub-section.

Click here to go to the document contents.

Or press {Alt Left Arrow} to return to previous text.

|-------------------|

Stored Connection Strings
a sub-section of the
AxHandle section



Address : jragan.com/axledoc_1.htm#15.10.37
-- . --

Each time that the ConnectionString command is used by AxHandle, he stores the "String". He also saves the connection strings when he creates the demo databases. If the new string is identical to one on file, he will not save it, but the slightest difference will cause it to be saved.

Press the open_db button to display all stored connections. To open the desired database, highlight the one needed and press the do_it button, or just double click the desired string.

In conformance with the AxleBase design philosophy, the AxHandle connection strings are saved in a text file that can be edited in notepad. It is named connects.txt.

-- . --

End of the Stored Connections sub-section.

Click here to go to the document contents.

Or press {Alt Left Arrow} to return to previous text.

|-------------------|

Demonstration Databases
a sub-section of the
AxHandle section



Address : jragan.com/axledoc_1.htm#15.10.40
-- . --

When the AxleBase project began, every time that a test garbaged the database, it had to be laboriously reconstructed by hand. (Yuck!) Therefore, AxHandle was given the ability to destroy and re-create test databases on demand.

Pressing the demo_db button will create a demonstration database domain, demoDom, under the app's location. Various databases will then be created in that domain; demo_main, demo_citizen, demo_seg, demo_virtual, and demo_audit. Each contains a dozen or so tables.

AxHandle contains scripts that consist of the commands and SQL statements required for the operations. When the button is pressed, AxHandle starts passing the commands to AxleBase.

The complete demo databases may be re-created at any time just by pressing the button. AxHandle asks AxleBase if they already exist, and if they do, AxHandle tells AxleBase to drop them, and then begins creating new ones.

The domain is preserved after it is first created. This is done to allow creating and populating databases with various domain-level parameters. It also allows you to create other databases in that domain. The entire domain and the demo databases may be removed by deleting the db directory.

The demos contain a few simple tables that contain some rows for experimentation. The column types are mixed so they can be used to test performance.

The demo_virtual database also contains a few virtual tables. Some of the virtual tables can function only if their attributes are modified to fit the local environment.

As it is being created, the system writes a script in the returns window that shows the commands that are used. This can be copied and saved for reference when creating other databases. If additional databases are created in the demo domain, AxHandle will retain them when re-creating the demo databases.

Feel free to manually alter the demo database and bang on it to experiment with it. If it becomes so badly corrupted that AxleBase cannot even destroy it, manually delete the entire \db directory under the app, and then press the demo button again.

-- . --

End of the Demo Databases sub-section.

Click here to go to the document contents.

Or press {Alt Left Arrow} to return to previous text.

|-------------------|

VLDB Expansion
a sub-section of the
AxHandle section



Address : jragan.com/axledoc_1.htm#15.10.45
-- . --

For "VLDB" testing, AxHandle has been given the ability to generate very large test tables. Each table that is created in the demonstration database may be expanded by selecting the appropriate option on the enlarger menu.

AxHandle uses individual SQL statements to insert rows into tables. He creates an individual statement for each insert and then passes the command to AxleBase.

Allow the generator to run for a day or two or whatever is required to generate a table of the needed size. Each table has a different rate of growth. Depending upon which table it is, a four hundred megahertz processor can generate a million or so rows every day or two.

Caution ! :
        This operation can fill a disk so it should be monitored.
        AxHandle has a row limit on his configuration screen. If an amount is entered before starting the operation, the table size will not exceed it.

AxHandle gives unique rows to some tables. Select the AxleBase command ShowTables to get the table names, and then use the ShowTable command to inspect the structure of each table.

HINT :
        For large tables, do a "SQL Count" query to get a row count. Then use the AxleBase "Row" clause in a SQL command to go directly to a specific area of the table for the operation.

-- . --

End of the VLDB Expansion sub-section.

Click here to go to the document contents.

Or press {Alt Left Arrow} to return to previous text.

|-------------------|

Testing AxleBase
a sub-section of the
AxHandle section


Address : jragan.com/axledoc_1.htm#15.10.50

Updated 20221013
last update 20221130
-- . --

Instead of just using a script to write test data and reports to disk, AxHandle actually drives AxleBase for the task, which tests many of the AxleBase commands and functions when the button is pressed.

AxHandle has additional miscellaneous tests built into it that he runs every time that he builds any database. They include many commands and SQL queries that are not used in building that database. You will see them run when you create a new demo database.

      - Report of AxleBase test.
      - AxHandle generates a report each time that he is commanded to test AxleBase, and prints it to the screen when it is complete. If there is an error during the run, he cancels the entire run and reports only that error, which saves tremendous time in tedious error searches.
      - The following report is expanded with blank lines to make it easier to read.
      - Count:
      - The job consists of every command that he is able to run and check autonomously. (That the absent-minded builder did not overlook.) It currently contains 588 identifiable discreet tests.
      - Some contain multiple tests, and some also contain intentional errors such as spelling and character case, to always insure that changes have not sensitized AxleBase to them.
      - Since it is actually a test, AxHandle checks each return, and will abort the entire job for any detected error, error message, anomalous condition, or unexpected return.
      - Inconsistency:
      - Commands in the test that are interdependent are sequentially checked for failed or inconsistent returns
      - Notes:
      - AxHandle prints notes within the report, and those have been prefixed with "*Note*" on this copy to make it more understandable.
      - Speed:
      - Digits before each command are approximate run times. Minutes-seconds-decimal parts of a second. Remember that the times reflect the fact that this was run on an old mechanical disk drive.
      - Where there are only zeros, the execution was faster than the computer could measure it. Because of the internal axleBase design and because it was compiled to native code using a C++ compiler, you will find that approximately 60% of the tests in the following report are that fast.
      - Returns
      - Returns from the encrypt and authenticate commands have been deleted from this copy to protect proprietary work.
      - Some very long parameter strings are truncated by AxHandle for readability.
      - Commands that produce a report such as the "ShowDomainAttributes" frequently have no printed return because AxHandle found no error or anomally in the return.
      - Some points will be obscured if you are not familiar with AxleBase. For example, AxHandle reports that the single SQL insert into the "T_CITIZEN" table inserted 50 rows instead of 1. But notice that the command specified an "Arrayed Insert", and the very long SQL insert string had to be truncated by AxHandle to display it.
      - Persistence:
      - All objects and data created by the test are left on disk afterward. They can be queried, altered, or deleted as you wish. If they are not damaged beyond recognition, the next test run will drop and recreate them.
      - Created are 5 databases containing 73 tables with a small number of data rows.
      - Simplicity:
      -The test is so easy to run that it was usually run many times per day during development.
      - When the test is complete, it uses the "Arrayed Insert" command to create an insert of the entire test with one test on each row into the T_DEMO_SCRIPT table. If you do a select * query, it will return a list of tests with descriptions.
      - Stress Tests:
      - Since the test has a heavy footprint, it was given a cycler on the AxHandle menu to allow it to run continuously to test the entire system, including hardware. Many such stress tests have been run.
      - Last test run:
      - 20201007.

* * * * * * * * *
The copy of AxHandle's report follows the next line of stars, and ends with the note,
"The copy of AxHandle's test report ends here.".
* * * * * * * * *

* * * * * * * * *
The copy of AxHandle's test report ends here.
* * * * * * * * *

-- . --

End of the System Tests sub-section.

Click here to go to the document contents.

Or press {Alt Left Arrow} to return to previous text.

|-------------------|

Continuous Cycling
a sub-section of the
AxHandle section



Address : jragan.com/axledoc_1.htm#15.10.55
-- . --

The previously described tests can be run in a continuous cycle from a menu option. This is designed for stressing AxleBase; running load tests. It is not designed to be a test of speed.

Select the stop option from the same menu to stop the tests.

A well designed application would recover when AxleBase returns an "Error". For example, if AxleBase reports a query timeout, the app might regenerate the failed request or ask the user if he wants to retry. However, AxHandle is a development tool, so it is designed to stop on error and display it.

The tests are designed to run against a fresh copy of the demo database. When they are started, AxHandle performs a few checks on the tables for that reason.

The slowest test cycle puts a minute between tests. That test can take over two minutes to stop because of the length of the pauses.

Since AxHandle is not multitasking, the cycling must be stopped before doing anything else. AxHandle should not be unloaded while a test is running.

"YieldProcessor" :
        Turning off the "YieldProcessor" toggle can increase the system load, but if a high load is attained with it off, it may be extremely difficult to stop a test. If multiple instances of AxHandle are run simultaneously against the same database, then a yield is necessary to force them to cooperate.

Logging :
        Logging is the best way to see what happens in a test, but logging will increase the system load. Running multiple "Instances" simultaneously with logging on may increase the load significantly.

If logging is on, its overhead and the impact of the log size should be assessed.

Some errors that can be logged cannot be passed back to the host, so AxHandle will not know about them. All errors that can be detected by AxleBase are logged if logging is on, whether or not they can be returned to the host.

Hardware danger :
        This feature of AxHandle is designed to stress the system. That includes the entire computer system. AxHandle is the tool that is used in the AxleBase development environment, so you can set up its tests to overwhelm a system and perhaps even destroy hardware and operating systems. Do not depend on an AxleBase collapse to protect your hardware, because AxleBase is designed to ignore everything until his job is done or everything is dead.

Test statistics and the SQL queries are displayed in the return window during the test cycling.

A test setup can be designed as needed. A single instance can be run at low speed to watch the operation, or can be run at high speed to watch the effect. Multiple instances can be run to load the system, and remote multiple instances can be run against a database to watch the effect. ( These are NOT recommendations. See the previous warning. )

-- . --

End of the Continuous Cycling sub-section.

Click to return to document contents.

Or press {Alt Left Arrow} to return to previous text.

|-------------------|

Step By Step Operation
a sub-section of the
AxHandle section



Address : jragan.com/axledoc_1.htm#15.10.65
-- . --

Load the system. Accept the license terms to display the main screen.

Press the demo_db button. This will create demonstration databases under the app. The path may be something like c:\program files\AxHandle\db\demo\

After it creates the demo database, it will it will remain open so you can immediately begin querying and investigating.

You can change to a different database with a couple of different methods. If using the ConnectionString command, enter the domain path which will be something like c:\program files\AxHandle\db\demoDom and enter the name of the database such as demo_virtual. Then press the do_it button.

Find the "ShowDomainAttributes" command and select it. Press the top do_it button. The domain's attributes will be displayed in the return window.

Select the "OpenDatabase" command. Type the name of a database, demo or demo_virtual in the parameters window. Press the do_it button. The database will be opened.

Select the "ShowDatabaseAttributes" command and press the do_it button. Attributes will appear that describe the currently open database.

Select the "ShowTables" command and press the do_it button. The names of the tables in the database will appear.

Select the "ShowTable" (singular) command. Enter the name of a table. Press the do_it button. The table's characteristics will appear. Now, try it with the ShowTableAttributes command.

Select the "ExecuteSql" command in the lower window. Enter a query in the lower parameter window, such as "select * from t_log". Press the lower do_it button. The rows will appear.

Try a select after unloading and reloading the app. You will find that it does not work. AxHandle creates a new "Manager" object and data "Vector" object for you when he loads, but you need to open a database as was done previously.

-- . --

End of Step By Step Operation sub-section.

Click to return to document contents.

Or press {Alt Left Arrow} to return to previous text.

_________________________
Database Server
a section of the
Test And Demo Software chapter



Address : jragan.com/axledoc_1.htm#15.20.00
-- . --

|-------------------|

Description
a sub-section of the
Database Server section



Address : jragan.com/axledoc_1.htm#15.20.10
-- . --

AxServer is a simple database server that uses AxleBase as its database manager. It demonstrates the server support that is built into AxleBase for a database server host.

AxServer uses the Socket Programming interface for communication. Its protocol stack is SysLink/ TCP/ IP.

( Pursuant to the commands of Him for whom I work, my software will transmit only that which is openly and simply specified. Furthermore, in His trust, care is taken to insure that every transmission is only what you would want if you had the time to study every transmission and all documentation.)

When it goes on line, AxServer loads an "Instance" of AxleBase in the background to do its work. An "AxHandle" client on a different computer can send commands to it and it will return the data or results.

When a communication session is established, only the server's AxleBase instance is used. The client passes commands straight to the server and the server passes them to AxleBase. The server then returns the result to the client.

The demo systems are not intended for production work. The Windows operating system requires a new handle for almost every event and the demo apps cannot release those handles so they eventually reach the Windows limits. AxServer hits the limit quicker than AxHandle because Windows communication objects also use handles.

( Reminder: The AxleBase API supports "ODBC" if you want to build an ODBC driver for your server.)

-- . --

End of the Description sub-section.

Click to return to document contents.

Or press {Alt Left Arrow} to return to previous text.

|-------------------|

What It Is Not
a sub-section of the
Database Server section



Address : jragan.com/axledoc_1.htm#15.20.20
-- . --

This is a simple demonstration app.

Not a production-quality system.

Not designed for high speed operations.

Not designed for unattended operation.
( Since it has a GUI it can display an error message for the user, which will hang all computer operations until the user returns to clear the message.)

It has limited error handling.

It cannot handle multiple NICs on either end.

The primary function of this database server is research and testing in the AxleBase lab so, unlike a true database server, this one is designed to stop processing and report when certain kinds of errors happen. Obviously, if for no other reason, that one prevents it from being used as a production server.

AxServer is not solid. The majority of the development effort is put into AxleBase and secondarily into the test apps. That leaves little time for communication development and leaves the server in a primitive state.

-- . --

End of the What It Is Not sub-section.

Click to return to document contents.

Or press {Alt Left Arrow} to return to previous text.

|-------------------|

Step By Step Start
a sub-section of the
Database Server section



Address : jragan.com/axledoc_1.htm#15.20.40
-- . --

The demonstration requires two computers that communicate with each other on a network.

Perform these operations in the sequence shown.

Uninstall "AxHandle" and AxServer if you already have them. New versions are needed.

Install AxHandle on a computer.

Install the server, AxServer, on the other computer.

Start AxServer and AxHandle.

Press the button on AxServer to start its server.

Press the server button on AxHandle to display the communication panel.

Enter the server's computer name and press the connect button.

Press AxHandle's demo_db button to create the demonstration database on the other computer.

If everything was done correctly, you will see the system building a database on the AxServer computer and then running a series of tests. The two systems will talk to each other during the process and will show you parts of their conversation.

After the tests are complete, you will be connected to the remote database so you can run tests. Select the ExecuteSQL option in the lower window, enter
    SELECT * FROM T_LOG, and press the do_it button.
( The server will return data to AxHandle and AxHandle will display it. )

-- . --

End of the Step By Step Start sub-section.

Click to return to document contents.

Or press {Alt Left Arrow} to return to previous text.

|-------------------|

SysLink Communication Protocol
a sub-section of the
Database Server section



Address : jragan.com/axledoc_1.htm#15.20.50
-- . --

"SysLink" is the application-level communication protocol that is used by the AxleBase suite. Any app that uses the SysLink / TCP / IP stack can communicate with AxHandle and AxServer.

The entire "SysLink" protocol can be seen on the jragan.com/ "SysLink" page on this web site.

See also the discussion of the AxleBase "Virtual Private Network".

-- . --

End of the Server SysLink sub-section.

Click to return to document contents.

Or press {Alt Left Arrow} to return to previous text.

|-------------------|

Point-n-Click Query App - Axon
a section of the
Test And Demo Software chapter



Address : jragan.com/axledoc_1.htm#15.30.00
-- . --

-- . --

End of the Query App section header.

Click to return to document contents.

Or press {Alt Left Arrow} to return to previous text.

|-------------------|

Description
a sub-section of the
Point-n-Click Query App section



Address : jragan.com/axledoc_1.htm#15.30.10
-- . --

Query options are contained in Axon's drop-down lists. Options can be selected by clicking on them until all are selected that are needed in a query. The query is then run by pressing a button.

After Axon is told to open a database, options such as table names, column names, etc., automatically fill drop-down boxes from the database, so the user has them at his fingertips. He selects whatever is needed and runs the query.

Connecting to a database loads all of the database's table names into a list from which can be selected the tables that are needed for the query. As each table is selected, its column names are automatically loaded into a drop-down list for selection. Up to six tables can be joined in a query.

The details of making a database connection can be a pain in the neck, so a database connection is saved after it is created. Many connections can be made, so the databases can be opened with point-n-click.

Data returns are displayed in Notepad.

-- . --

End of the Query App Description sub-section.

Click to return to document contents.

Or press {Alt Left Arrow} to return to previous text.

__________________________________________________
Chapter 3
Embedding And Running AxleBase
__________________________________________________

Address : jragan.com/axledoc_1.htm#20.00.00
-- . --

-- . --

End of the chapter header.

Click to return to document contents.

Or press {Alt Left Arrow} to return to previous text.

_________________________

Designing and Coding
a section of the
Embedding And Running AxleBase chapter



Address : jragan.com/axledoc_1.htm#20.30.00
-- . --

-- . --

End of the Designing and Coding section header.

Click to return to document contents.

Or press {Alt Left Arrow} to return to previous text.

|-------------------|

Data Connectivity
a sub-section of the
Designing and Coding section



Address : jragan.com/axledoc_1.htm#20.30.15
-- . --

AxleBase is designed to be embedded inside a host application. He talks directly to the host. As soon as he is installed, the host application can send commands to him.

He provides his own interface for programming. No other software is needed. Not even an "ODBC Driver".

If AxleBase is embedded in a server, then that server may use an ODBC driver. The AxleBase interface is designed to support the ODBC protocol without additional programming.

-- . --

End of the Data Connectivity sub-section.

Click to return to document contents.

Or press {Alt Left Arrow} to return to previous text.

|-------------------|

Indexing
a sub-section of the
Designing and Coding section



Address : jragan.com/axledoc_1.htm#20.30.17
-- . --

An AxleBase "Index" is different.

A database manager cannot be optimized for both the large and the ordinary. One or the other must be slighted, so AxleBase is internally optimized for very "Large" data object indices. Since AxleBase is not intended for heavy concurrent access, the degradation on very small tables may not be noticeable, but the improvement on very large tables will be obvious.

Small Repeating Datasets :
      Many columns in databases contain small repeating datasets. The most common is the "Boolean" column, where a billion rows will have only two different values in the entire column.
      A standard index of that kind of column can be slower than no index, so AxleBase offers a special index, type 61, for it.
      AxleBase always forces boolean columns to have a type 61 index. For other columns, he analyzes the data and forces it to type 61 if it consists of a small repeating dataset.
      But what about columns that currently have no data or that are ambiguous? In that case, you can specify a type 61 in the "CreateIndex" command. For example, lookup link values from other tables are sometimes small repeating datasets.
      If queries become extremely slugish in a large table, an indexed column may need to be re-indexed with this type.
      A few thousand rows are usually enough for AxleBase to recognize a small repeating dataset, so re-indexing will cure the problem unless it is impossible for him to recognize the data as discussed above.
      ( See ForceType in the "CreateIndex" command sub-section. )

Boolean Columns :
      AxleBase forces boolean columns to have a type 61 index.
      There is usually no speed advantage in boolean column indices.

Indexing a very large AxleBase table can have a tremendous positive impact on speed. Scanning a twenty billion row table, that is stored on disk drives, for a value can take weeks or months. An AxleBase index can sometimes reduce that time to a fraction of a second.

( One of the tables that was built in the lab to test AxleBase, contains 100 Billion rows.
      If the hardware could read a row from it
      in a millisecond,
      then scanning that table for a row would
      run around the clock for 5.5 months.)

The AxleBase approach to indexing is unlike that of ordinary database managers. This is necessary to optimize AxleBase for his specialized abilities.

A management method that sometimes appeals to the "DBA" is to index every column in the database, but that can slow some operations in a very large database. Since the slowed operations in normal databases are not heavily used by most people, the cost is seldom noticed. For example, if it takes two thousandths of a second to insert a row instead of one thousandth of a second, nobody notices.

But what happens if the database manager is handling a truly large table? One thousandth of a second per row will add a week to the construction of a billion-row table. And if the table will become very big, that millisecond can turn into months.

The big name brands also sometimes use that approach. In some cases, a database manager will automatically create an index without the knowledge of the DBA. However, to do that in an AxleBase database could be disastrous simply because AxleBase is designed for the management of very large data objects. Therefore, the DBA can expect no unexplained gain in speed as sometimes happens with a big name brand.

A point of interest is the way that AxleBase handles a multi-column index. He creates the multi-column index and, while he is at it, he creates single-column indices for each column in the multi-column index. His query optimizer knows that, so he mixes and matches as needed by each query.

AxleBase has special tools to help the DBA with building and indexing. An index in a table will slow a high speed build greatly. Dramatic speed improvement can sometimes be attained by first building the table, and then indexing in a separate operation.
      ( See the optional segment clause in the "CreateIndex" command sub-section.)

A normal table build usually hides the slow speed caused by indexing because the system spends much time just waiting for work. It is therefore sometimes advisable to allow the index to build during the table build for normal slow operations so that it can be immediately used.

AxleBase recognizes complex relationships between data characteristics, data object size, and the environment. He also knows that the characteristics of that data may change in ways that are important but are too subtle for a human to detect. He uses specialized internal algorithms that help him decide upon the best way to index each data object for the fastest build speed and for the fastest index concomitant with his specialized mission objectives.

Before indexing a table file, he analyzes the entire file to choose the best options for it. If the file has little or no data, then AxleBase makes his best guess about how to index it, but it is only a guess, so in that case, the index for that segment should be rebuilt after the segment is filled.

Some analysis operations use the buffer to determine the characteristics of the final index. The larger the buffer, if it is not too large for the hardware, the more efficient will be those indices after they are built.

When possible, the fastest insert and index operation, by far, is attained by first completely populating a table, and then indexing it afterwards. Creating an index while a table is built will result in much slower indices.

If the hardware or operating system stops or has a problem while indexing a file, then the entire index for that file must be restarted.

Reading a table that has been partially indexed may result in data being missed until that data is indexed. Therefore, for a "VLDB" that is being built over a long period and that must be used during that period, it may be prudent to bring each table's data file on line only after it is fully populated and entirely indexed.

See also the "VLDB" Addendum to the "CreateIndex" command, and the ShowIndices command in the API chapter.

-- . --

End of the Indexing sub-section.

Click to return to document contents.

Or press {Alt Left Arrow} to return to previous text.

|-------------------|

Remote Access And Paths
a sub-section of the
Designing and Coding section



Address : jragan.com/axledoc_1.htm#20.30.20
-- . --

AxleBase is designed for the host, so he will always be running on the same machine on which his host is running. The objects that he creates are expected to be used only by his host on the local machine.

There will be times, however, when it is desirable to share local data with remote locations and the organization does not want to build a database server into their host. In such a case, domains and databases can be shared across a network without a database server.

Objects are shared after they are created. If a database is shared, then its controlling domain will also be shared.

The "ShareDatabase" command is covered in the API chapter.

Of course, sharing in that manner obviates "Security" controls.

-- . --

End of the Remote Access sub-section.

Click to return to document contents.

Or press {Alt Left Arrow} to return to previous text.

|-------------------|

Installation Design
a sub-section of the
Designing and Coding section



vAddress : jragan.com/axledoc_1.htm#20.30.25
-- . --

These features may help in the design of an installation.

1		AxleBase supports multiple database domains in an installation.
2		Each domain supports multiple client databases.
3		Distribution across multiple spindles and computers is supported for speed.
4		Its domain/client database structure can help organize and control.
5		Multiple host apps can share a database.
6		A host app can tell its AxleBase instance to create multiple database manager "Instances", and each will configure itself independently.
7		Each of those database manager instances can open a different database.
8		The master app can use all of those instances simultaneously.
9		Each database manager instance can support any number of data objects that can operate independently.

-- . --

End of the Installation Design sub-section.

Click to return to document contents.

Or press {Alt Left Arrow} to return to previous text.

|-------------------|

The Database Domain
a sub-section of the
Designing and Coding section



Address : jragan.com/axledoc_1.htm#20.30.30
-- . --

AxleBase groups databases into domains. An installation can have any number of domains and each domain can contain many databases. The attributes and data for each domain are stored in its own database.

The character of each domain is controlled by the DBA. Each database can be in its own domain, all can be in a single domain, they may be assigned to domains by a certain characteristic, or whatever. The domain is an administration tool:   It can be used or ignored, but AxleBase requires that every database must be in a domain.

Before a database can be opened, its controlling domain must be opened. A database domain is opened by the "Manager" object according to the attributes stored in the domain's database. It reads the attributes and uses them to configure itself. After the domain is active, its client databases can be created and/or opened.

A domain may be opened regardless of whether or not it exists. If it does not exist, the specified location is valid, and the create parameter is "yes", then AxleBase initializes a new domain database for the domain at that location. After a domain is opened, its client databases may be created or opened.

Let us make this point explicit: Opening a domain either opens it, if it exists, or creates and opens it. That is why there is no "CreateDomain" command. For that reason, the DBA should take care in opening domains, or he will end up with cluttered disks.

Pseudo Code Example:

1.	dim oMgr as Manager
2.	set oMgr = new Manager
3.	oMgr. OpenDomain "\path\demoDom\"
4.	oMgr.OpenDatabase "prodClient3"

In steps 1 and 2 above, a new Manager object is created. The new Manager object is named oMgr in the example, but can be named anything appropriate. In step 3, oMgr is told to open the domain that is named demoDom with the "OpenDomain" command. In step 4, oMgr is told to open the client database named prodClient3 with the "OpenDatabase" command.. oMgr is then ready to work with the prodClient3 database.

A database domain may be distributed across spindles, controllers, and computers. The client databases are not required to be on the same medium and may be located as desired. The same is true of other objects as covered in subsequent sections.

See also: OpenDomain; DropDomain; CreateDatabase; ConnectionString

-- . --

End of the Database Domain sub-section.

Click to return to document contents.

Or press {Alt Left Arrow} to return to previous text.

|-------------------|

Concurrent Operations
a sub-section of the
Designing and Coding section



Address : jragan.com/axledoc_1.htm#20.30.40

Updated 20221013
-- . --

Concurrent operation is the simultaneous use of a database by multiple systems or people. Without controls, concurrent operations can disrupt each other by locking data objects and by trying to update the same data. The results are unpredictable and can result in data loss, and sometimes even the loss of entire data objects. AxleBase was designed with the concurrency problem in mind so that he can handle multiple users, but it should be noted that his trials and tests ended when his development ended and did not include the heavy concurrency that is handled by ordinary database managers.

AxleBase Complexity:
      If the host is a server and only a single server is allowed to access each database, then much of the concurrency problem is thereby handled. But AxleBase was designed for far more complex organizational operation. He allows multiple hosts and even multiple database servers to run against the same database. Although the hosts are entirely independent and could therefore conflict in theory, each and every AxleBase "Instance" operates with the problem in mind to protect the data.
      ( Yes, even multiple servers per database such as might be found in multi-system military operations. See "high speed" in the "SysLink Protocol" document.)

The tests that are published on the "Notable Tests" document present the results of concurrency stress tests. As can be seen from those results, AxleBase can handle a substantial load, but it should be stressed that he is not designed for high-speed, heavy-concurrency "OLTP". Actual use should not exceed the limits of those tests until more concurrency testing is done.

AxleBase Failsafe:
      ( Concurrency testing is an operation that must be run to failure so that a valid value can be reported; i.e., the test load must be increased each time that the test is run to force a system failure. The failure point will be found somewhere below that point.
      There are also complex issues within that forced failure that must be studied. For example, how will the internal AxleBase failsafe structure react to that kind of failure when it is forced upon him?
      Those failure tests were planned but the project was stopped before they could be done.
      Please also read the "Concurrency" section on the "Test" page.)

Failure Envelope:
      His engineering is for a benign failure envelope. In other words, if a concurrency failure does occur, it will take place within the "Error" handler envelope. The result will usually be client lockout and an extreme condition would be database shutdown.

System Locks:
      All "System Locks have a built-in timeout that is set by the "DBA" so that they will self-clear after that period. An extreme problem can be handled with a database Purge by the "DBA" and should seldom require a restore.
      AxleBase manages his own System Locks, so he does not use the operating system or the host for object locking. That design decision was made for flexibility, portability, and to allow many simultaneous remote hosts, but it has a shortcoming of which the DBA must be aware; i.e., along with that decision was the design decision to allow the DBA to directly access the database. Therefore, the DBA must always keep that in mind during operation and during his "Security" design.
      See also the "System Lock Design" section and the "Concurrency Locking" sub-system.

A decision should be made during the design of the host app concerning what the host should do when AxleBase reports a "Lock" conflict.

-- . --

End of the Concurrent Operations sub-section.

Click to return to document contents.

Or press {Alt Left Arrow} to return to previous text.

|-------------------|

Coding Tips & Techniques
a sub-section of the
Designing and Coding section



Address : jragan.com/axledoc_1.htm#20.30.50
-- . --

AxleBase tries to make life as easy as possible for the developer.

Character case is usually unimportant. Do it the way that you want. The system will accept anything and try to standardize internally for you.

If white space is required for delimitation, be sure that at least one character is present. Otherwise, use it as you want and AxleBase will clean up after you.

AxleBase does not store space padding. He trims leading and trailing spaces from data before saving it. All in-code comparisons must be constructed accordingly. (This is not in compliance with ANSI-92 SQL.)

Where parentheses, commas, colons, etc., are used, such as in standard SQL commands, be sure that they are present. However, do not be overly concerned about the presence or absence of a space before or after a parenthesis or a comma or whatever. Wherever possible, AxleBase attempts to read what you mean and not what you write.

AxleBase will accept formatting in a SQL command. Most of us format long SQL statements so that we can understand them when they quit working six months later.

Never use an undocumented feature that you might stumble across in AxleBase. Such features tend to change or go away during development.

AxleBase does not return nulls. If a value is null, there is nothing to return, so he returns nothing. Perhaps that seems silly, but it saves the host developers from writing tons of extra code to protect their systems. Some database managers return nulls, which crashes the system in every return.

Where a command tells AxleBase whether or not to do something, you can give him a simple yes or no. A state may or may not become true or false after the command is executed, but that state is after the command is submitted. His "Boolean" column data type also accepts yes and no.

-- . --

End of the Coding Tips & Techniques sub-section.

Click to return to document contents.

Or press {Alt Left Arrow} to return to previous text.

|-------------------|

Important Coding Note
a sub-section of the
Designing and Coding section



Address : jragan.com/axledoc_1.htm#20.30.55


Updated 20221013
-- . --

I am just plain tired of my own inability to use bad logic, regardless of masses of people who do it. After many years of programming, I am well aware that the zeroth element is how the programming community identifies the first element of a set, but that is far from logical.

Of course, it is possible to become comfortable with logic flaws, as evidenced by the many old software engineers around the world. And it is possible to aspire to poor logic, as evidenced by the many young wannabe software engineers. But I have become fed up with it.

Therefore, AxleBase respects mathematical logic by numbering the first element of a set as the first element.
      The first element of a set is the first element.
      The number of elements in a set is the number of elements in the set.
      It is not the number of elements in the set minus one.
      To get the fourth row, tell AxleBase that you want row 4 ; not row 3.
      For the first row, tell AxleBase that you want the first row; not row 0.
      In this entire massive project, there is not a single zeroth item. None.
( Please look at the absolute stupidity of those points to see why I am adamant about this matter.)

I am hoping that few thinking people will object to this particular deviation from an industry standard. The fact that something is accepted, commonplace, and standard sometimes means only that millions of people are of equal intelligence.

-- . --

End of the Coding Note sub-section.

Click to return to document contents.

Or press {Alt Left Arrow} to return to previous text.

|-------------------|

The AxleBase Interface
a sub-section of the
Designing and Coding section



Address : jragan.com/axledoc_1.htm#20.30.60

Updated 20221013
-- . --

AxleBase has multiple interfaces, any one of which may be selected for the current session. One of them is the standard interface and the others are abstractions of the standard interface. The usage of each is covered in the "Interface" section of the API chapter. All of them have access to the entire AxleBase functionality, but each is designed to meet a unique inter-system interface theoretical function.

"Standard Interface" :
      The "Standard Interface maintains the close interface between the software engineer and the system that most developers expect. It presents the entire set of commands and functions to the software engineer with close interaction.

His entire standard interface resides in two objects: the "Manager" object and the "Vector" object. The interface is immediately available when those objects are instantiated. Commands are sent to those two objects and all responses come from them.

"Abstract Interface :
      The abstracted interfaces are abstractions of the standard interface. Their purpose is to allow simplification of server hosts, and that allows much smaller hosts on the network. That does not, however, simplify the job of the developer because he must still understand the commands that are being abstracted to insure that they are correctly formatted and used.

"UniCom" and The "UniString" Interfaces :
      There are two abstracted interfaces; i.e., UniCom and UniString. Each of them has only a single command; i.e., UniCom and UniString. UniCom is an abstraction of the standard interface to a higher level. UniString is an additional abstraction of UniCom to another level.

The "Unicom Interface" accepts any standard interface command with its parameters. The "UniString Interface" accepts only a single "String" that can contain any standard command with all of its parameters. Abstraction and simplification does come at a price, however. Be sure to closely read the discussions in the API chapter.

To use UniCom or UniString, instantiate the "AbstractInterface" object. It will instantiate any objects that it requires. Do not instantiate the standard interface objects when using the AbstractInterface object because the results will be unpredictable. Remember that the AbstractInterface object creates any objects that it needs such as the "Manager" and the "Vector".

AxleBase is just another DLL on the computer. When he is installed on a computer, his programming interface is immediately available to any host system. If you know how to use Windows objects in your code, then you can use AxleBase. He runs as a COM server inside a host system, and only inside a host system.

The syntax that is used to instantiate the objects depends upon the language of the host system and how the developer wants to use the objects. If the developer wants a tightly coupled interface, then he can compile a reference to AxleBase within the host system. The code can then refer directly to the objects.

For example, the "AxHandle" system does not have a reference compiled into it. The objects change so often in the development environment that a hard coded reference interfered with testing, so AxHandle creates interface objects on the fly. An existing DLL can be unregistered, a new one placed where AxHandle can see it, and when AxHandle starts, he registers the new one and creates objects on the fly.

-- . --

End of the AxleBase Interface sub-section.

Click to return to document contents.

Or press {Alt Left Arrow} to return to previous text.

|-------------------|

The Manager Object
a sub-section of the
Designing and Coding section



Address : jragan.com/axledoc_1.htm#20.30.65
-- . --

The "Manager" object is an internal AxleBase software object that handles the management and administrative affairs of databases and domains. He creates domains, databases, tables, etc.; destroys objects; maintains them; handles "Security"; performs backups and Purges; etc. (Data is handled by the other object.)

Depending upon the language, using the Manager object follows this pattern :
      Declare the object.
      Instantiate the object.
      Pass the command.
      Check for "Error" messages.
      Destroy the object.
The code might look something like this.
      dim oMgr as Manager
      set oMgr = new Manager
      oMgr.OpenDomain
      oMgr.OpenDatabase "prodClient3"
Close the domain and database, and destroy the object.
      set oMgr = nothing

Before a database can be opened, the appropriate database domain must be opened. After a domain is opened, its databases can be opened.

A database must be opened before any action can be taken on it. If it does not exist, it must be created and opened.

Opening a database requires the execution of thousands of lines of code and many disk reads and writes. When the same database will be opened and closed repeatedly throughout the host system, a developer may decide to open and configure a Manager once at the top of his code and close it only as the host prepares to shut down.

-- . --

End of the Manager Object sub-section.

Click to return to document contents.

Or press {Alt Left Arrow} to return to previous text.

|-------------------|

The Data Vector Object
a sub-section of the
Designing and Coding section



Address : jragan.com/axledoc_1.htm#20.30.70
-- . --

The "Data Vector" object is an internal AxleBase software object that handles data. He updates, inserts, deletes, retrieves, etc. He is the system vector for data. SQL queries such as select, insert, update, and delete are passed to him to tell him what to manipulate or return. The Vector object is a vector in both the mathematical and biological sense.

There are two ways to create a data Vector object. One uses an object creation command such as the VB CreateObject command, and the other way tells a "Manager" object to create it.

When a Vector object is created, it automatically connects to the Manager object.

Using the other method, a Manager object is told to create a Vector object. A database that the Manager object opens is available to the Vector through the manager. Each Manager object can create any number of Vector objects and each may be in use. ( For command syntax, see the API chapter, Manager section, DataObjectCreate command. )

In either case, a Manager object may support any number of data Vector objects.

The AxHandle system was creating free-standing Data objects at one time. Currently, there is always a Manager object available for a Vector as soon as the Vector is created.

A line of Visual Basic code from AxHandle that creates a Vector object:

A line of Visual Basic code from AxHandle that tells the AxleBase Manager to create an object:

Depending on the programming language, using the data object may follow this pattern :
      Declare the Manager object.
      Instantiate the Manager object.
      Open the database domain.
      Open the target database.
      Check for "Error" messages.
      Declare the Vector object.
      Instantiate the Vector object.
      Pass the SQL command to the Vector object.
      Check for error messages.
      Do the job.
      Destroy the Vector object.
      Destroy the Manager object.

-- . --

End of the Data Vector Object sub-section.

Click to return to document contents.

Or press {Alt Left Arrow} to return to previous text.

|-------------------|

Client Connection Protection
a sub-section of the
Designing and Coding section



Address : jragan.com/axledoc_1.htm#20.30.80
-- . --

When a client operates in a hostile environment, such as a mobile client, one can expect to frequently experience disruption of communications during long-running queries. AxleBase provides a function to ameliorate short-term communication disruptions during massive queries. When used by a client, it almost guarantees a data return if the query is received. If all clients are in a hostile environment, the "DBA" can tell the system to apply the function to all queries. (The maximum return size that it will protect is two billion " tuples".)

Every query is assigned an identifier. The user can append an indentifier to his query, or if he does not, the system generates a unique identifier for it. The query user is usually unconcerned about it and may never know of it, but it serves as a handle on the query. After running a query, the "ShowDatasetAttributes" command will show the identifier of the current query, which will also be the ID of the dataset that it successfully created.

Client Usage :
      When a query is received and processed, the result will be available even if the session connection is broken. Reconnect to the server and to the database. Then issue a "ReturnCache" command using the query name in the optional parameter and with a " tuple" count if needed. The data will return normally.

System-Wide Protection :
      If all clients are subject to such disruptions, the "DBA" can configure the system to defer all returns to protect them. In that case, the client software should generate a query name for each query. If the connection is lost, the client software can show the query id to the user, or add it to the next query. The query name must be protected to avoid "Security" problems.

Timeout :
      Each database has a timeout for its work location.
      The "DBA" maintains that value.
      A deferred return will remain on file for that duration.
      ( The system has various timeout values.)

Server Loss :
      If the server completes the query, then the deferred dataset return will be safe through server crashes, shut downs, and loss of the database connection. The dataset will persist for the time that the "DBA" specified for the temp timeout in the database configurations. If the "Instance" crashes during the query or while returning the dataset, then, of course, the dataset will be corrupt.

Also, see the "ReturnCache", the "CacheReturn" SQL clause, and the "CacheReturns" system configurations and the "API" chapters.

-- . --

End of the Connection Protection sub-section.

Click to return to document contents.

Or press {Alt Left Arrow} to return to previous text.

|-------------------|

Visual Basic Examples
a sub-section of the
Designing and Coding section



Address : jragan.com/axledoc_1.htm#20.30.85
-- . --

Visual Basic code to open a database might look something like this:
      dim oMgr as Manager
      set oMgr = new Manager
      sReturn = oMgr.OpenDomain ( "c:\domain\" )
      sReturn = oMgr.OpenDatabase ( "mydb" )
      sReturn = oMgr.ShutDown
      set oMgr = nothing

Visual Basic code to open a client database and run queries might look something like this:
      dim oMgr as Manager
      set oMgr = new Manager
      sReturn = oMgr.OpenDomain ( "c:\axlebase\db\" )
      sReturn = oMgr.OpenDatabase ( "mydb" )
      dim oQuery as Vector
      set oQuery = new Vector
      sReturn = oQuery. ExecuteSQL ("select * from myTable")
      for i =1 to oQuery.TupleCount
      sVariable = oQuery.ColumnContents ( 1, i )
      next i
      set oQuery = nothing
      sReturn = oMgr.ShutDown
      set oMgr = nothing

-- . --

End of the VB Examples sub-section.

Click to return to document contents.

Or press {Alt Left Arrow} to return to previous text.

|-------------------|

Microsoft Access Examples
a sub-section of the
Designing and Coding section



Address : jragan.com/axledoc_1.htm#20.30.90
-- . --

See the previous Visual Basic examples.

-- . --

End of the Access Examples sub-section.

Click to return to document contents.

Or press {Alt Left Arrow} to return to previous text.

|-------------------|

WinBatch Examples
a sub-section of the
Designing and Coding section



Address : jragan.com/axledoc_1.htm#20.30.95
-- . --

WinBatch code to open and/or create a database would resemble the following. ( Some code lines are broken for readability. )

; first, create the AxleBase database object
oMgr = ObjectOpen("AxleBase.Manager")

#DefineFunction fnInitializeDatabase(oMgr, sDatabase)
      sSql = ""
      sSql = strCat( sSql, "CREATE TABLE T_TEST ( ")
      sSql = strCat( sSql, "PROCESS string ( 20 ) , ")
      sSql = strCat( sSql, "PARAM_NAME string ( 35 ) , ")
      sSql = strCat( sSql, "PARAM_VALUE ( 30 ) )")
      sReturn = oMgr.CreateTable( sSql )
      if sReturn <> "" then goto unloader
      sSql = ""
      sSql = strCat( sSql, "CREATE TABLE T_LOG ( " )
      sSql = strCat( sSql, "DATE_TIME string ( 30 ) , " )
      sSql = strCat( sSql, "PROCESS string ( 20 ) , " )
      sSql = strCat( sSql, "LOG_NOTE string ( 50 ) )")
      sReturn = oMgr.CreateTable( sSql )
      if sReturn <> "" then goto unloader
      :unloader
      return sReturn
#EndFunction

#DefineFunction fnOpenDatabase(oMgr,
            sMasterDatabase, sDatabase)
      sReturn = oMgr.OpenDomain( sMasterDatabase )
      if sReturn <> "" then goto unloader
      sReturn = oMgr.ShowDatabase
          if sReturn == ""
          sReturn = oMgr. CreateDatabase( sDatabase )
          if sReturn <> "" then goto unloader
      else
          iFound = StrIndex( sReturn,
            sDatabase, 1, @FWDSCAN )
          if iFound < 1
              sReturn = oMgr.CreateDatabase( sDatabase )
              if sReturn <> "" then goto unloader
          endif
      endif
      sReturn = oMgr. OpenDatabase( sDatabase )
      if sReturn <> "" then goto unloader
      sReturn = oMgr.ShowTables
      if sReturn == ""
          sReturn = fnInitializeDatabase(oMgr, sDatabase)
          if sReturn <> "" then goto unloader
      else
          ; could also check here for specific tables
      endif
      :unloader
      return sReturn
#EndFunction

#DefineFunction fnReadData( oMgr, )

      ; first, create an AxleBase data object
      LastError( )
      oDs = ObjectOpen("AxleBase.Vector")
      iErr = LastError( )
      if iErr != 0
          sReturn = "Failed to create an AxleBase DataSet object."
          goto unloader
      endif

      ; set the data connection for the dataset
      ; Winbatch can't handle complex objects
      ; so tell the object to set its own connection
      ; This feature was added and will be in the next release.
      sReturn = oDs.Connect( oMgr )
      if sReturn <> "" then goto cleanup

      sReturn = oDs. ExecuteSQL( "Select count(*) from myTable" )
      if sReturn <> ""
          ; a count can return a number as an error
          if isnumber(sReturn) then
          if sReturn < 0 then sReturn =
          "**ERROR: The AxleBase database manager
          returned an
          error during the data retrieval."
          endif
          if StrSub( sReturn, 1, 8) == "**ERROR:"
          then goto cleanup
      endif

      i = oDs.tupleCount
      if i < 1 then goto cleanup

      sReturn = oDs.tuple

:cleanup
      objectClose( oDs )

:unloader
      return sReturn
#EndFunction

sReturn = fnOpenDatabase( oMgr, "c:\db", "c:\db\thisApp" )
; the above will open the database.
; if it does not exist, the function will create it.
if sReturn <> "" then goto unloader

; close the AxleBase database object
ObjectClose(oMgr)

-- . --

End of the WinBatch Examples sub-section.

Click to return to document contents.

Or press {Alt Left Arrow} to return to previous text.

_________________________

System Lock Design
a section of the
Embedding And Running AxleBase chapter



Address : jragan.com/axledoc_1.htm#20.40.00
-- . --

See also the following sub-sections, and the "LockObject" command.

-- . --

End of the System Lock Design section header.

Click to return to document contents.

Or press {Alt Left Arrow} to return to previous text.

|-------------------|

General
a sub-section of the
System Lock Design section



Address : jragan.com/axledoc_1.htm#20.40.10
-- . --

The AxleBase locking mechanism is designed to support his very special objectives that include very "Large" data entities. For example, if an AxleBase "Instance" needs to read an index for a table query, he suspends other operations until finished with the index, applies the appropriate read lock to the index, does the operation, and unlocks the index. This results in faster over-all operation in the AxleBase environment.

Locks take precedence over "Security" Grants.

See Also :
      the "LockObject" user discretionary command.

-- . --

End of the General sub-section.

Click to return to document contents.

Or press {Alt Left Arrow} to return to previous text.

|-------------------|

AxleBase Lock-Space Domains
a sub-section of the
System Lock Design section



Address : jragan.com/axledoc_1.htm#20.40.20
-- . --

Domain	Description
D	Discretionary.
P	Persisted.
A	Autonomic.

A lock-space domain is a concept and is not a functional object. Its application to the subject helps describe how the system actually works.

Discretionary Lock Domain

Discretionary locks may be applied and removed by the host or user at any time by using the "LockObject" command. For example, the "DBA" might lock the database in preparation for a Backup. That type of lock will exist until the user exits, or the user removes the lock, or the lock expires. If an "Instance" abends and leaves a discretionary lock, it will expire and will be removed by the next system "Purge".

Persisted Lock Domain

The distributed architecture and independent nature of the AxleBase instances requires persisted as well as discretionary locks.

Persisted locks are similar to discretionary locks. The difference is that they are object attributes and, therefore, are persisted indefinitely. They are controlled by the AlterTableAttribute, AlterDatabaseAttribute, and the AlterDomainAttribute commands.

Autonomic Lock Domain

Autonomic locks are invisible system locks and are described here only to complete the picture. They are seldom noticed and are visible only when a desired action is denied because of a system lock. A complete description of the autonomic locks would be so large that it might require separate documentation.

AxleBase is continually applying and removing autonomic locks during any operation. The autonomic locks are applied and removed by the system as needed to support user activity. The previous index example used an autonomic lock. Autonomic locks are owned and controlled by the system and are part of the source of the AxleBase magic.

Share locking is used whenever possible. Share locks permit simultaneous reads, but prevent writes to the object while it is being red. In some areas, such as small system tables, he uses only write locks to preclude all reads until the write is complete and employs Spinlocks to prevent read failures.

Autonomic locks allow data updates to use dirty reads or read-through locks that allows the data to be red during an update. They increase speed and are used with success in many database manager brands. A row update failure is not retried. If the update fails, an "Error" is returned and the host or user is expected to take the appropriate action. Row updates are checked by automatic system rereads.

Discretionary locks, persisted locks, and autonomic locks are operationally integrated and respect each other. Autonomic locks take precedence, but discretionary and persisted locks honor each other.

See also the "LockObject" user discretionary command.

-- . --

End of the Lock Space sub-section.

Click to return to document contents.

Or press {Alt Left Arrow} to return to previous text.

|-------------------|

Concurrency Locking
a sub-section of the
System Lock Design section



Address : jragan.com/axledoc_1.htm#20.40.30
-- . --

Before addressing concurrency, it is important to observe a few very important facts in the AxleBase operation.
      Extremely large tables are involved and each may be distributed across a network.
      A database may be directly accessed by many remotely located systems.
      The system may be a distributed database manager whose components may simultaneously access tables at high speed.
      The entire system must run on desktop computers.

Concurrency is handled entirely by autonomic locks. Their activity is never registered in the lock tables since they are answerable only to each other, but they generate "Error" messages appropriate to each concurrency problem. The host must be prepared to react to those error messages.

An important part of concurrency control is the "Spinlock" value that may be adjusted by the "DBA". When an "Instance" encounters an object with a system lock, it performs a "Spinlock" until the object is available up to the specified interval. If the object is not released in that period, the instance executes an access failure. The spinlock value must be neither too large nor too small to adequately support concurrency for each environment in which the distributed system is operating. (See the Spinlock section of the Configuration chapter.)

The query timeout and the connection timeout are used in ways that are similar to the "Spinlock". In general, the query timeout is applied to a table object, the "Spinlock" value is applied to system objects, and connection timeouts are applied to domains and databases.

As AxleBase operates, he uses many kinds of "Locks" on various objects and sometimes locks objects simultaneously and sometimes sequentially in a single operation. It is, therefore, difficult to describe the operations in this small document. In general, he uses share locks for reads and exclusive locks for data updates, but that is only a general statement.

When he begins querying a table, he places share locks on table objects. As he finishes with each object, he removes the lock. Therefore, it is possible that a complex query could, in some situations, be interrupted by another "Instance" putting a write lock on the table's index or pointer table, for example. That could happen if the query accessed the index multiple times. It might also happen if the table has billions of rows because its pointers are accessed. Although unlikely, those events are possible. Tests, however, show AxleBase performing well at his concurrency design objective.

The requirements of updates are more complex than those of reads. Keep in mind the fact that AxleBase must be prepared to update petabyte-sized tables. The rows must first be located, and then red like a query. They must next be prepared for the update, and then the new rows must be committed, and finally, the old rows must be deleted.

The easiest way to control an update would be to lock the entire table and all of its component objects, and that works in ordinary database managers, but that would ruin concurrency in very "Large" tables, so it is not a viable option for AxleBase. The traditional atomic transactions were also considered because they work so well for Oracle and others, but they would slow operations tremendously in large tables.

The AxleBase solution for updates is to update with shared locking. All of the target rows are located, red, marked, and recorded, and new rows are constructed. Then the writes begin. The new updated rows are all inserted into the table and the old ones are then deleted. For very large tables, all updates are performed simultaneously for the entire table.

Each update step moves through the table like a wave. When a step reaches the end of the table, the next step-wave starts at the beginning of the table.

Notice that a reader can jump into the middle of an update and query a row before the update is committed. That is by design; the data is presented "as is" until the commit.

A simple insert is another matter. If it is a normal insert, which is usually a relatively small number of rows, it will be a quick operation, and locks will usually not even be noticed. If it is a very large table build, then the "DBA" wants a high speed operation so that millions of rows can be inserted around the clock and may even build off site. In either case, a write lock is needed, so a write lock is placed on each table segment until the write is complete or until the segment is filled.

Note that those concurrency locks are not recorded and will not show up in the ShowLocks report. All of those lock operations are expected to be far quicker than the generation of a report. Even the build of a very large table uses quick intermittent locking.

See Also ShowLocks command in the API chapter, and the "LockObject" user discretionary command.

( See the Testing section for results of concurrency stress tests. )

-- . --

End of the Concurrency Locking sub-section.

Click to return to document contents.

Or press {Alt Left Arrow} to return to previous text.

|-------------------|

AxleBase Lock Granularity
a sub-section of the
System Lock Design section



Address : jragan.com/axledoc_1.htm#20.40.40
-- . --

Level	Description	Lock Domain Control
1	db domain	D, P
2	database	D, P
3	table	A, P
4	segment	A
5	column	P
6	row	A, P
7	file	A

D	Discretionary.
P	Persisted.
A	Autonomic.

Column level locking has not been implemented due to a perceived lack of need. It may be re-considered later.

Locks may be placed at each level, but are vertically additive through the object hierarchy. For example, an operation involving a table may automatically apply locks for the table, database, and domain before attempting the operation. An operation at the database level will first check both the database and the domain locks.

-- . --

End of the Lock Granularity sub-section.

Click to return to document contents.

Or press {Alt Left Arrow} to return to previous text.

|-------------------|

Lock Types
a sub-section of the
System Lock Design section



Address : jragan.com/axledoc_1.htm#20.40.50
-- . --

AxleBase CRUD Table

Code	Description	Domain	Level
c	create	P	1,2,3
r	read	P	1,2,3
u	update	P	1,2,3
d	delete	P	1,2,3
e	execute	P	1,2
x	exclusive	D	1,2
i	in use	A
z	system	A

See previous table for lock domain codes.

The lock types follow an extended crud model. Each is a denial of a type of service. They are additive and multiple types may be set simultaneously. They are also additive hierarchically, so no level over-rides another. ( Note that the denial of service is unlike the "Security" system that grants service.)

A type x exclusive lock takes an object offline and locks out all other users and processes until it is removed.

A lock type may be used in multiple levels and multiple lock domains. For example, an exclusive lock is discretionary and not persisted. A "z" lock is the only system lock that may sometimes appear as an explicit code.

-- . --

End of the Lock Types sub-section.

End of the System Lock Design section.

Click to return to document contents.

Or press {Alt Left Arrow} to return to previous text.

_________________________

Column-Data Types
a section of the
Embedding And Running AxleBase chapter



Address : jragan.com/axledoc_1.htm#20.50.00
-- . --

-- . --

End of the Column-Data Types section header.

Click to return to document contents.

Or press {Alt Left Arrow} to return to previous text.

|-------------------|

General
a sub-section of the
Column Data Types section



Address : jragan.com/axledoc_1.htm#20.50.05
-- . --

A column-data type is neither a column type nor a data type, but is a combination of the two. They agree in most cases, so we tend to refer to them as one or the other, but the technical difference should be remembered because the two are not always the same.

If you have a favorite name-brand database manager, there is a comparison table in the "Data Type Mapping" sub-section. ( This builder has worked with only a dozen or so database manager brand names.)

-- . --

End of the General sub-section.

Click to return to document contents.

Or press {Alt Left Arrow} to return to previous text.

|-------------------|

BLOBs
a sub-section of the
Column Data Types section



Address : jragan.com/axledoc_1.htm#20.50.10
-- . --

BLOB is an abbreviation for Binary Large OBject. A blob can be anything that can be stored by a computer in a file. It is therefore, not considered data. It might be a photograph, music, text, etc. A BLOB is any object that can be retrieved and manipulated by software that is specially built for that type of object. (In theory, anything can be stored as a BLOB, but storage of anything that is not a Binary Large OBject can produce administrative problems, and might cause data loss.)

Every BLOB in the database has a handle that completely and uniquely identifies the BLOB and that completely and uniquely identifies its location. The BlobHandle in the Windows operating system is the path and name, so the BlobHandle is a file pointer.

A query for the BLOB object will return its handle which is a pointer to the file. The pointer can be used by BLOB handling software to load the BLOB object. AxleBase may be embedded in the BLOB handler or the handler can use a different host to do the querying.
        For example, the system builder's personal system handles his music collection in a BLOB table. Selecting the title of a song tells the system to load the player and tells the player to play that BLOB, or selection of the Beethovan composer tells it to play all of his work.

The blob column width is discretionary because it must be able to contain the entire BlobHandle. Other characteristics are identical to the "String" type.

The operation of this type is unlike any of the others.
        A row may have an empty BlobHandle.
        A row may have a null BlobHandle.
        BlobHandles must be delimited like string data.
        BLOB objects are validated. If not empty and not null,
            the BlobHandle must identify a valid BLOB object.
        Drops and deletes are designed to protect BLOB objects.
        BLOB objects are NOT destroyed by:
                Table drops.
                Database drops.
                Table truncations.
                Row deletes.
        Systems may use standard SQL queries of BLOB rows.

Advanced Topic :
      The BLOB column-datatype is the recommended manner of handling BLOBs. AxleBase also allows the "DBA" to design tables that allow the storage of BLOB objects within a table's column, which is discouraged.
      Remember that loss of a table that contains BlOB objects in a column will also lose the BLOBs, which is one of the reasons for recommending their remote storage.
      After investigating the many management and adminstrative problems with the BLOB data, if you are certain that you want to store BlOBs within a data table :
      "Create" a new table with a BLOB column.
      "Alter" the column so it does not use delimiters that may be found in the BLOBs.
      If needed, you can also "Alter" the rows so their terminators do not conflict with BLOBs.
      Fixed width rows are strongly recommended for speed, if possible.
      "Indexing" of at least one of the standard columns is recommended for speed. It might, for example, be the BLOB indentifier, such as a name.

Tests :
      Please note that the "tests document" carries stress tests using very large row queries, "Very Large Row Stress" using up to 10 megabytes per row.

Experience :
      The AxleBase builder's personal system uses AxleBase to store his data including two types of BLOBs; audio and visual. To use a BLOB, he selects the one that he wants from a drop-down list, which tells AxleBase to load its type of player, hands the BLOB data to the player, and activates the player. He can also select multiple BLOBs.
      That personal system has been in use for an indeterminate length of time that may go back two decades.

-- . --

End of the BLOB sub-section.

Click to return to document contents.

Or press {Alt Left Arrow} to return to previous text.

|-------------------|

Boolean
a sub-section of the
Column Data Types section



Address : jragan.com/axledoc_1.htm#20.50.20
-- . --

The boolean type has only two value states that usually specify affirmation and negation.

Table columns are defined as boolean with no length. The boolean type is stored as a single numeric character of either a 1 or a 0, and that is the form in which it is returned. The one is affirmative and the zero is negative.

The following boolean values are recognized by AxleBase in most cases.

-- . --

End of the Boolean sub-section.

Click to return to document contents.

Or press {Alt Left Arrow} to return to previous text.

|-------------------|

Date
a sub-section of the
Column-Data Types section



Address : jragan.com/axledoc_1.htm#20.50.25
-- . --

Table columns are defined as date with no length. Storage and return are in the standard "CoreDate" protocol format that has been truncated to its leftmost eight digits; i.e., YYYYMMDD; e.g, 19620130, which many people read as January 30, 1962 or perhaps as 30 January 62.

Since the DATE type is a truncated version of the coredate protocol, it has lost the BC descriptor character. If dates BC are required, then the standard "DateTime type or the standard "DateTimex type must be used.

The DATE type is based upon the "CoreDate" protocol.

All operations use the truncated coredate format. The convert function may be used to reformat other date formats.

See also "DateTime, "DateTimex, "Time, and "Timex data types.

( Storage is in human readable form without tokenization in consonance with the AxleBase design objectives.)

-- . --

End of the Date type sub-section.

Click to return to document contents.

Or press {Alt Left Arrow} to return to previous text.

|-------------------|

Datetime
a sub-section of the
Column-Data Types section



Address : jragan.com/axledoc_1.htm#20.50.30
-- . --

Table columns are defined as datetime with no length. Storage and return are in the standard sixteen digit "CoreDate" format; i.e., YYYYMMDDHHMMSSNN; e.g. 2010012410230400, which many people read as January 24, 2010 at 10 23 04 AM or perhaps as 24 January 10, 10 23 04 AM.

The coredate protocol specifies that the final character of the string may be a digit or a minus sign descriptor character. If it is a digit value, the date is AD; if it is a minus sign, the date is BC.

The last two digits are decimal parts of a second. Tenths and hundredths. If greater precision is required, see the DateTimex type.

The acceptable DateTime range is from 99990101 BC to 99991231 AD. Dates outside that twenty thousand year range must be stored as String types.

The DateTime type is based upon the "CoreDate" protocol.

All operations use the standard coredate format. The convert function may be used to reformat other date formats.

See also "DateTime, "DateTimex, "Time, and "Timex data types data types and the "CoreDate" protocol.

( Storage is in human readable form without tokenization in consonance with the AxleBase design objectives.)

-- . --

End of the Datetime sub-section.

Click to return to document contents.

Or press {Alt Left Arrow} to return to previous text.

|-------------------|

Datetimex
a sub-section of the
Column-Data Types section



Address : jragan.com/axledoc_1.htm#20.50.35
-- . --

Table columns are defined as datetimex with no length. Storage and return are in the standard extended twenty one digit "CoreDate" format without the optional time zone designator; i.e., YYYYMMDDHHMMSSNNNNNNN; e.g. 201001241023040062384, which many people read as January 24, 2010 at 10 23 04 AM or perhaps as 24 January 10, 10 23 04 AM.

The coredate protocol specifies that the final character of the string may be a digit or a minus sign descriptor character. If it is a digit value, the date is AD; if it is a minus sign, the date is BC.

The acceptable DateTimex range is from 99990101 BC to 99991231 AD. Dates outside that twenty thousand year range must be stored as String types.

The last seven numeric characters are decimal parts of a second. Accuracy is limited to one millionth of a second.

The DateTimex type is based upon the coredate protocol that may be found in the appendices.

All operations use the standard extended coredate format. The convert function may be used to reformat other date formats.

See also "DateTime, "DateTimex, "Time, and "Timex data types.

( Storage is in human readable form without tokenization in consonance with the AxleBase design objectives.)

-- . --

End of the Datetimex sub-section.

Click to return to document contents.

Or press {Alt Left Arrow} to return to previous text.

|-------------------|

Integer
a sub-section of the
Column-Data Types section



Address : jragan.com/axledoc_1.htm#20.50.40
-- . --

A column width should not be specified for this type. The actual storage width is 20 characters.

The Integer data type accepts any literal printable whole number up to twenty characters that may include a minus sign. Commas and decimals are disallowed.

The Integer data type was added to speed indexing because indexing the numeric type is far slower and the operation of numeric indices is slower.

AxleBase does not tokenize, categorize, segregate or alter numbers. They are stored as literal strings.

The twenty characters sets the maximum size. If the number of characters in an integer exceeds twenty, the number is truncated to the left-most twenty characters. Therefore, a number may be no larger than 99, 999, 999, 999, 999, 999, 999, and no smaller than -9, 999, 999, 999, 999, 999, 999.

See also the "NUMERIC data type.

( Storage is in human readable form without tokenization in consonance with the AxleBase design objectives.)

-- . --

End of the Integer sub-section.

Click to return to document contents.

Or press {Alt Left Arrow} to return to previous text.

|-------------------|

Numeric
a sub-section of the
Column-Data Types section



Address : jragan.com/axledoc_1.htm#20.50.41
-- . --

A column width should not be specified for this type. The actual storage width is 20 characters.

The Numeric data type accepts any literal printable number up to twenty characters that may include a sign and a decimal point. Decimals must follow the American standard. Symbolic representation is not acceptable. Commas are disallowed.

Where possible, the Numeric type is recommended for speed. The Numeric data type was added to speed indexing because indexing the Numeric type is far slower and the operation of the resulting indices is slower.

AxleBase does not tokenize, categorize, segregate or alter numbers. Thus, float, decimal, tinyint, bigint, integer, plus, minus, etc. ad infinitum, are all stored as the numeric type. This also means that AxleBase respects precision. If a fifteen decimal place number is handed to AxleBase, he precisely stores all fifteen places.

The twenty characters set the value limit and precision of the number. If the character count in a number exceeds twenty, the number is truncated to the left-most twenty characters.

See also the "Integer" data type.

( Storage is in human readable form without tokenization in consonance with the AxleBase design objectives.)

-- . --

End of the Numeric sub-section.

Click to return to document contents.

Or press {Alt Left Arrow} to return to previous text.

|-------------------|

Serial
a sub-section of the
Column-Data Types section



Address : jragan.com/axledoc_1.htm#20.50.45
-- . --

A column width need not be specified for this type. The actual storage width is 20 characters. Each table can have only one "Serial" column type.

The Serial type is numeric and is maintained by the system. Each row of a column may be expected to have a unique numeric value for that column and row. Values are incremented for each new row, but are not necessarily consecutive and cannot be predicted because of other potential activity in the table.

Where the system requires a value, such as in an arrayed insert, any value or a null value may be specified for the serial column in the SQL statement. The least confusing option may be the placement of a zero in that position. The actual insert will become a system-generated value.

A speed increase may be achieved in some cases by using a Serial column as the table key. This is certainly true where a table requires a key and there are no unique indices in it. Consistent with the AxleBase objectives, this column is not automatically indexed as some database managers do. The database administrator makes those decisions.

The values may be expected to be unique through the entire column across segment boundaries. However, be cautious of assuming uniqeness in every Serial column. For example, virtual concatenated tables will certainly not be unique, and there are other exceptions.

Serial columns cannot be updated. A serial column in a row that is updated will not be changed. The value of a Serial column may not indicate the physical location of a row in a table because some operations cause the system to move rows.

At this time, the maximumn value for each Serial column is 1x10^18, or 1,000,000,000,000,000,000.

To add a serial column to a table that is in production :
      Back up the database.
      Copy the table file to another location.
      Drop the table.
      Create the table with the serial column.
      Import data from the copy.
      Re-index.

-- . --

End of the Serial sub-section.

Click to return to document contents.

Or press {Alt Left Arrow} to return to previous text.

|-------------------|

String
a sub-section of the
Column-Data Types section



Address : jragan.com/axledoc_1.htm#20.50.50
-- . --

It is called String because it is any string of characters including the IBM ASCII extension. The maximum length must be specified when creating a table, and that will become the enforced width of the column.

( This type is sometimes referred to as "alphanumeric", which is fine as long as we remember that the AxleBase system can also include all of the other characters. )

Control characters and control strings are removed from string data before it is inserted into a database to safeguard the database. They are returned when data is retrieved. However, it may be better to store strings that contain extended or unprintable ASCII characters as "Blob" data.

AxleBase trims leading and trailing white space in and out. (Since this is contrary to the ANSI 92 standard, it may be revisited in the future.)

The maximum String length is determined by the maximum row length, which is approximately two gigabytes. For long String data, BLOB storage is sometimes a better management alternative.

Review the AxleBase Limits sub-section before designing data objects.

-- . --

End of the String sub-section.

Click to return to document contents.

Or press {Alt Left Arrow} to return to previous text.

|-------------------|

Time
a sub-section of the
Column-Data Types section



Address : jragan.com/axledoc_1.htm#20.50.55
-- . --

Table columns are defined as time with no length. Storage and return are in the standard "CoreDate" format that has been truncated to its six digit time; i.e., HHMMSS; e.g. 202304, which many people read as 8:23:04 P.M., or as 20:23:04.

For precision better than a second, see the "TIMEX" data type.

BC times cannot be stored in this data type. See the "DateTime" and the "DateTimex" types for BC time storage.

The Time type is based upon the "CoreDate" protocol.

All operations use the truncated coredate format. The convert function may be used to reformat other "Date" formats.

( Storage is in human readable form without tokenization in consonance with the AxleBase design objectives.)

-- . --

End of the Time sub-section.

Click to return to document contents.

Or press {Alt Left Arrow} to return to previous text.

|-------------------|

Timestamp
a sub-section of the
Column-Data Types section



Address : jragan.com/axledoc_1.htm#20.50.57
-- . --

Table columns are defined as timestamp with no length. Storage and return are in the standard "CoreDate" format of datetime with the optional two-character time zone and the three character environment code for a total of twenty-one characters.

The column content is a system-generated datetime value that is inserted by AxleBase when the row is created and it is not maintainable. The value includes the standard "CoreDate" time zone appendix of two digits and includes a three character date-time environment. The time zone and environment codes may be changed in the database configuration parameters.

The CoreDate standard specifies that no characters may be empty, but a governing body does not yet exist for code assignation to date-time environments. Therefore, the default environment code is TER, meaning standard terrestrial, until a governing body exists.

( Note that the value inserted into the table will be determined by the inserting AxleBase "Instance". The business system or host software should be designed with that in mind.)

See also "DateTime, "DateTimex, "Time, and "Timex data types.

( Storage is in human readable form without tokenization in consonance with the AxleBase design objectives.)

-- . --

End of the Timestamp sub-section.

Click to return to document contents.

Or press {Alt Left Arrow} to return to previous text.

|-------------------|

Timex
a sub-section of the
Column-Data Types section



Address : jragan.com/axledoc_1.htm#20.50.60

-- . --

Table columns are defined as timex with no length. Storage and return are in the extended "CoreDate" format that has been truncated to its thirteen digit time; i.e., HHMMSSNNNNNNN; e.g. 2023040060523, which many people read as 8:23:04 P.M., or as 20:23:04.

The last seven numeric characters are decimal parts of a second. Accuracy is limited to one millionth of a second. If accuracy of that depth is not needed, perhaps the "Time" data type might be more viable for the application.

BC times cannot be stored in this data type. See the "DateTime" and the "DateTimex" types for BC time storage.

The Timex type is based upon the "CoreDate" protocol.

All operations use the truncated extended coredate format. The AxleBase "DateConvert" function may be used to reformat other date formats.

See also "DateTime, , "Time, and "Timex data types data types.

( Storage is in human readable form without tokenization in consonance with the AxleBase design objectives.)

-- . --

End of the Timex sub-section.

Click to return to document contents.

Or press {Alt Left Arrow} to return to previous text.

|-------------------|

Mapping From Other Systems
a sub-section of the
Column-Data Types section



Address : jragan.com/axledoc_1.htm#20.50.90
-- . --

Unfortunately, there is not enough time to study all of the products on the market. The following are data types from some of the more popular database managers with suggested data type mappings. An import of the source type will probably be accepted in the specified AxleBase type.

Included are Oracle, MySql, MsSql, InterBase, Ms Access, Paradox, FoxPro, and Ingress. The list may not be exhaustive, but can provide extrapolative assistance.

-- . --

End of Other System Data Types sub-section.

Click to return to document contents.

Or press {Alt Left Arrow} to return to previous text.

_________________________

AxleBase Error Protocol
a section of the
Embedding And Running AxleBase chapter



Address : jragan.com/axledoc_1.htm#20.60.00
-- . --

See also the following and the sub-sections following this section :
    "ClearLastError",
    "ShowErrorList",
    "ShowLastError"
    "Comm Hide Error AxleBase"
    "Comm Hide Error In Server"
    "Comm Hide Error Syslink"
    The Axsys super-system "Error Controller"

-- . --

End of the Error Protocol section header.

Click to return to document contents.

Or press {Alt Left Arrow} to return to previous text.

|-------------------|

Introduction
a sub-section of the
AxleBase Error Protocol section



Address : jragan.com/axledoc_1.htm#20.60.10
-- . --

The host system is expected to be able to react to all error situations. AxleBase's deeply embedded nature precludes all GUI error messages, so all user interaction must be handled by the host system. If the host system is incapable of accepting AxleBase errors, then Axlebase logging may be turned on to capture them, but that is not recommended because operation should not be blindly continued after an error.

All operations are capable of returning error messages as variable length character "Strings. If an unexpected return is detected, it is probably an error message. In any event, all returns should be inspected for an error notification.

The last error is stored and is not cleared until the next error overwrites it. The host system can clear that message. The LastError functions are covered in the API chapter.

If the activity log has been turned on, when an error message is returned, it is additionally written into the activity log. A message is sometimes written as multiple log rows. The first row always contains the header and the identifier. Logged errors are usually terminated by the entry, "End of error report.**".

For most errors, AxleBase will simply raise the error and abort the process. In any case, AxleBase will attempt to recover and continue operation through the error situation. In the event of a system crash, AxleBase will attempt to log the situation before going down, but that is not possible in some operating system crashes.

In the event that a table becomes corrupted beyond repair, and there are no backups, the host application may delete the table. AxleBase will re-initialize it and continue operations.

With Reservations :
      The completion of some operations may be desired regardless of errors. For example, a database drop quickly reaches a point where a halt would leave a mess of errors. If errors occur after that point, the system will attempt to work through them. The return will include a list of all errors and the first error will be a "completed with reservations" error.

-- . --

End of the Error Introduction sub-section.

Click to return to document contents.

Or press {Alt Left Arrow} to return to previous text.

|-------------------|

Sub-System Shortcomings
a sub-section of the
AxleBase Error Protocol section



Address : jragan.com/axledoc_1.htm#20.60.15
-- . --

Shortcoming 1. :
The unforseen and unexpected :
      As mentioned in the previous "Introduction" sub-section, AxleBase attempts to monitor the state of the entire environment as well as his own state. When any error hits, his error handling sub-system attempts to trap it, analyse it, and report it before any damage is done.
      However, the realistic fact is that the error domain is so large that some situations are beyond his control, and some unimagined events may slip past him. But a great effort has been expended in protecting data in storage and data in transit. Where the operators take advantage of the many AxleBase sub-systems, the builder expects extreme data integrity and protection.

Shortcoming 2. :
The overwhelming error cascade :
      When an error hits anywhere in the system, control is passed to the error handling sub-system. It stops operations, compiles an error report including error and situation characteristics, and the report begins bubbling up from the interior of the system.
      However, a subsquent error may then occur. If that happens, it will over-write the initial error.
      That behavior was detected early in AxleBase development. For example, opening a database is complex and a problem can generate a cascade of errors. In such situations, AxleBase sometimes attempts to build an error chain report. But such reports quickly become uselessly complex.

Being unable to correct such problems at the root caused the builder to turn to unusual solutions. See the "Fault Tolerance" sub-section of the "Advanced Technologies".

-- . --

End of the Sub-System Shortcomings.

Click to return to document contents.

Or press {Alt Left Arrow} to return to previous text.

|-------------------|

Error Message Format
a sub-section of the
AxleBase Error Protocol section



Address : jragan.com/axledoc_1.htm#20.60.20
-- . --

Format of error messages:
**ERROR: [ type ]: [ source ]: AxleBase: errID: text: [ addendum ]

The purpose of this message format is to allow unattended, or autonomous, systems to automatically process and react to error messages.

The return consists of seven elements. The element separator consists of a colon and two spaces. Elements may sometimes be zero length. Only elements 1, 4, 5, and 6 are required, but all separators are always present to increase processing speed.

AxleBase may sometimes include responses from other systems in the addendum when those might be helpful. Therefore, when evaluating an error, the host should proceed from the header to avoid the confusion of appended responses.

The first element is the message header. The message header is always present and consists of the ten-character string,

If AxleBase can identify the type of error, the type may follow the header. Otherwise, the type may be blank. The type has variable content.

The source of the error follows the type. It is usually blank. The source is the source of the error message and not the cause of the error. The source has variable content.

So that the host can positively identify the message, the string "AxleBase" follows the source. Character case will usually be as shown, but may be changed under some circumstances or by other systems.

The error identifier, errId, is a five byte alpha-numeric identifier. It always follows the AxleBase identifier and precedes the text message. Host code that references specific errors must be reviewed when upgrading to a new release of AxleBase. All error codes currently consist of an alpha character followed by four digits.

Element six, the "text", is the literal text description that is intended for human communication. Its text string is standard and usually describes only one message identifier. To enhance human readability and to format log entries, text stings will sometimes contain characters 13 and 10 and white space.

The addendum is additional explication that is sometimes present. It is intended to amplify and/or qualify the standard text message, but does not change the ID. It is frequently an empty string.

A given message may be generated by various sources for various reasons and causes. Therefore, an error message may sometimes appear to be duplicated by some identifiers, sources, etc.

-- . --

End of the Error Message Format sub-section.

Click to return to document contents.

Or press {Alt Left Arrow} to return to previous text.

|-------------------|

Show Exceptions
a sub-section of the
AxleBase Error Protocol section



Address : jragan.com/axledoc_1.htm#20.60.30
-- . --

The error master list is made available to the host application by the "Manager" object. Use the ShowErrorList command to return a list of all of the errors, or use the optional error number parameter to return the specified error.

Syntax :
ManagerObject.ShowErrorList errorNumber

Returns the message specified by errorNumber. If errorNumber is blank, the entire list is returned with each message terminated by characters 13 and 10, carriage return and line feed.

The identification number and the text are returned. The size of the entire list varies and depends upon the current system release. It may be fifteen to twenty thousand bytes.

Example:
dim oMgr as Manager as
set oMgr = New Manager
sReturn = oMgr.ShowErrorList
sReturn will contain the entire list.

Example:
dim oMgr as Manager as
set oMgr = New Manager
sReturn = oMgr.ShowErrorList "E3025"
sReturn will contain "E3025: Column width exceeds 60,000."

The interface also provides a means of recalling the last error. See "ShowLastError"

-- . --

End of the Show Exceptions sub-section.

Click to return to document contents.

Or press {Alt Left Arrow} to return to previous text.

|-------------------|

Standard Error List
a sub-section of the
AxleBase Error Protocol section



Address : jragan.com/axledoc_1.htm#20.60.40
-- . --

As described in the previous sub-section, use the ShowErrorList command to return a list of all of the errors, or use the optional error number parameter to return the specified error.

The following is the list of AxleBase standard error messages as of July 2022 :

C0001: SAM is obsolete, which precludes the specified operation.
C0002: An invalid or unrecognized SAM was encountered. Expect a corrupted database.
C0003: An object is upgraded to the current SAM. Reload all systems immediately.
C0004: Database catalogue upgraded to current SAM. Recommend domain re-open.
C0005: Table catalogue upgraded to current SAM. Recommend database re-open.
C0006: Caution: One or more items were upgraded to the current SAM.
C0007: Reminder: The evaluation version is not intended for production.
C0008: Unlicensed system. Please request a valid AxleBase license.
C0009: License requirements are not met.
D0001: Under construction or consideration. Currently unavailable.
D0002: Query complexity level exceeded current development level.
D0003: Not supported at this time.
D0004: Test stopped at this point.
D0005: Processing aborted by operator or host. ' done by the abort utility.
D0006: Timeout. The requested timeout was exceeded.
D0007: Processed to completion with reservations.
D0008:
D0009: SysLink protocol error.
E1001: The command or parameter is invalid.
E1002: Node exclusion. ' not an error. just excluded from the job.
E1003: Authentication is invalid.
E1004: This AxleBase instance is already being used.
E1005: Un-indexed table scans are blocked. Contact your DBA for advice.
E1006: DDL is disabled by this database's DBA. Create, drop, alter, etc.
E1007: Requested object or value was not found.
E1008: Invalid object structure for specified operation.
E1009: Parameter length exceeds maximum allowed.
E2001: Row count update failed. Run purge with force to repair the table or segment.
E2002: Database is in an inconsistent state.
E2003: Database contains an item that cannot be removed.
E2004:
E2005: Database drop failed after partial processing. System may be inconsistent.
E2006: A database must first be opened.
E2007: Database cannot be opened because it belongs to a different domain.
E2008: Database creation failed for unknown causes.
E2009: Database has no table definitions.
E2010: Database contains no tables.
E2011: Database not found in catalogued location.
E2012: Database is not in the catalogue.
E2013: Domain database catalogue is empty.
E2014: Database specification is invalid.
E2015:
E2016: A domain must be opened first.
E2017: Domain specification is invalid.
E2018:
E2019: Domain location is invalid.
E2020: Database already exists in this domain.
E2021: Database is already open.
E2022: Database must be closed first.
E2023:
E2024:
E2025: System location contains unrecognized objects.
E2026: Path cannot be created.
E2027: Domain activation failed.
E2028: Domain drop failed after partial processing. System may be inconsistent.
E2050: Location is invalid.
E2051: That computer or its network is down or inaccessible.
E2052:
E2053: The location/path already exists.
E3001: Value is not numeric.
E3002: Value is illogical.
E3003: Parameter is invalid.
E3004: Database catalogue was not found and could not be initialized.
E3005: A database catalogue action was not recognized.
E3006:
E3007: Configuration file creation failed.
E3008: Parenthetical construct is invalid or unrecognized.
E3009: Multi-level parenthetical construct not yet available.
E3013: Data type is invalid.
E3014: Column name was not found where expected.
E3015: Column size is erroneous.
E3016:
E3017: Name contains a disallowed character.
E3018: Name length exceeds the maximum.
E3019: Names must start with an alpha character.
E3020: Name or value is a reserved word.
E3021: Column name is duplicated.
E3022: Database catalogue is corrupted.
E3023: Table catalogue is corrupt.
E3024:
E3025: Erroneous column type.
E3026: Column specification is erroneous.
E3027: Table row terminator is erroneous
E3028: Table is not in the database.
E3029: Table source type is invalid.
E3040: Table already exists.
E3041:
E3042: Import command is invalid.
E3043: Import source does not exist.
E3044: Import failed at row number -
E3045: Concurrent database connections have reached the currently set limit.
E4004: Requested column name index is below zero.
E4005: Requested column name index is greater than the number of elements.
E5001: Request does not match the specified data return protocol.
F0001: Unrecognized operation in file open.
F0002: File is not open.
F0003: Unable to open file.
F0004: Unrecognized file type.
F0005: Update failure.
F0006: Erroneous copy spec.
F0007: Location is invalid, unavailable, or can't be seen from here.
F0008: Object destruction failed.
F0009: Read past end of table.
F0010: File is already open.
F0011: Spinlock failure.
F0012: File is unavailable, invalid, or can't be seen from here.
F0013: Table seg is missing or unavailable.
F0014: Network or infrastructure failure. Database connection lost.
F0015: Data failover failed.
F0016: A data failover executed successfully. Please resend your request.
F0017: File is corrupt.
G0001: Log initialization failed.
G0002: Log use without initialization.
G0003: Logging must be turned on for the requested operation.
G0004: Buffer size exceeded by the operation.
K0001: Access denied.
K0002: Specified access denied to the specified object.
K0003: You have not been granted CREATE access to the specified object.
K0004: You have not been granted READ access to the specified object.
K0005: You have not been granted UPDATE access to the specified object.
K0006: You have not been granted DELETE access to the specified object.
K0007: You have not been granted EXECUTE access to the specified object.
K0008:
K0009:
K0010: Unrecognized security operation.
K0011:
K0012:
K0013:
K0014:
K0015: A conflicting, duplicated, or ambiguous grant exists.
L0001: Lock timeout encountered on the specified object.
L0002: Object is locked.
L0003: Lock failure. Object cannot now be locked.
L0004: Lock failure for specified row. Lock or unlock.
L0005: Lock code is invalid.
L0006: Lock is inappropriate for the operation.
L0007: Lock has expired.
L0008: Lock collision. ' object is locked.
M0001: Object exceeds the 2x(10^19) size limit.
M0002: SPT not found for seg number.
M0003: Segment specification is invalid.
M0004: SPT is corrupt.
M0005: SPT file is corrupt.
M0006: Object exceeds the 2.1 gig limit.
M0007: Seg name is invalid.
M0008: Seg size is too small for current operation.
M0009: Seg write map is invalid.
M0010: Seg location in SQL is not in a write map.
M0011: Stop encountered in the table write map.
M0012: Seg write map is exhausted.
S0001:
S0002: Backup failed.
S0003: Archive purge failed.
S0004: Archive contains an unrecognized or non-generational object.
S0201: The Vector object is not connected to a database.
S0202: Database is not open.
S0203: Object is not in the database.
S0204: Invalid object or variable specification.
S0205: A blank query was passed.
S0206: Ambiguous column qualifier or column name mismatch.
S0207: Column names not specified.
S0210: Table is undefined.
S0211: A table is not specified for column definitions.
S0302: Table is already keyed.
S0303: Index name is already used.
S0304: Unique index violation.
S0305: Table is not keyed.
S0306: Index storage location is invalid.
S0307: Table is corrupt. ' bad file, etc.
S0308:
S0309: Index structure failure.
S0310: Index requested for segments larger than 2.1 gig.
S0311: Purge table before indexing to remove deleted rows.
S0312: Index requested for invalid data type.
S0400: SQL statement is invalid, incomplete, or not recognized.
S0401:
S0402: SQL keyword not found where expected.
S0450: SQL function specification is invalid or unrecognized.
S0451: SQL function return request is illogical in current context.
S0501: SQL FROM clause was not found where expected.
S0502:
S0503: SQL FROM clause has an extraneous comma.
S0504: A column name may be needed. Use asterisk for count functions.
S0601:
S0602: SQL value is wider than the target column.
S0603: SQL statement is invalid in the INTO clause.
S0604:
S0605: SQL INSERT of null into a column defined as not nullable.
S0606: SQL INSERT value count does not match the column count.
S0607: SQL INSERT values were not found where expected.
S0608:
S0609: SQL INSERT attempted without an empty value and without a null.
S0610: SQL contains a non-numeric variable without delimitation.
S0701: SQL JOIN construction is invalid.
S0702: SQL table alias is invalid.
S0720:
S0721: SQL statement is incomplete or invalid near the ORDER keyword.
S0722: SQL ORDER BY clause specifies an invalid direction.
S0730: SQL statement table name was not found where expected.
S0731: SQL statement column identifier is invalid, unspecified, or unidentifiable.
S0732: SQL statement column names were not found where expected.
S0733: SQL statement specifies a blank column.
S0734: SQL statement has 'AND' or 'OR' where a column was expected.
S0735: SQL statement has 'AND' or 'OR' where a table name was expected.
S0736: SQL ROW limit clause is invalid.
S0737: SQL statement has unrecognized elements at the end.
S0738: SQL SEGMENT clause is invalid.
S0739: SQL ROW clause cannot be used with an indexed where clause.
S0740: SQL UPDATE column name is missing.
S0741: SQL UPDATE value is missing.
S0750:
S0751: SQL WHERE clause is incomplete.
S0754: SQL WHERE clause contains an unidentifiable variable.
S0755: SQL WHERE clause contains an invalid or unrecognized logic specification.
S0756: SQL WHERE clause is invalid.
S0757: SQL WHERE clause is invalid or unrecognized.
S0758: SQL contains an incorrectly constructed AxleBase function.
S0759: Host is expected to manipulate data after the return.
S0803: The table opener requires a file type specification.
S0804: Table was not found in the database.
S0805: Statement has an invalid logic connector.
S0806: SQL SELECT INTO cannot target an existing table.
S0807:
S0808: No database is defined by the loader.
S0809: A value cannot be typed as specified.
S0811: Data type is invalid.
S0812:
S0813:
S0814: Attempt to move beyond the beginning of the data set.
S0815: Attempt to move beyond the end of the data set.
S0816: The dataset is empty.
S0817: No current tuple pointer.
S0818: Tuple not found.
S0819: An unbalanced variable delimiter was encountered.
S0820: Invalid delimiter encountered.
S0821: Query timeout.
S0822: Job is incorrectly constructed.
S0840: Virtual table has no target name. ' alias
S0841: Virtual table has no location. ' alias
S0842: Virtual table file does not exist.
S0843: Virtual table cannot complete that operation.
S0844:
S0845: Virtual connection failure. 'these two are used differently
S0846: Virtual connection not available and FailOpen is true. 'those are used differently
S0847: Virtual makeString is invalid in the table attributes.
S0860: A shared table cannot be altered.
S0913: Invalid column encountered.
S0914: Invalid column count encountered.
S1103: Row update failed.
S1104: Serial columns cannot be updated.
S1105: Successfully reversed a failed update. Error(s) follow.
S1106: Failed to reverse a failed update. Check your data. Error(s) follow.
S1107: Failed transaction encountered! Exit the database and confer with your DBA.
U0001: An uncatalogued error was encountered.
U0002: There may be a problem with a computer.
U0003: The computer's dynamic memory has been exceeded.
U0004: The computer stack space has been exceeded.
U0005: The command failed.
U0006: The infrastructure has a problem. Hardware, operating system, etc.
U0007: Internal error.
U0008: Operation failure. ' for complex ops that return multiple errors or addenda.
U9999: DEV STOP. Administrative stop in the AxleBase lab.

-- . --

End of the Standard Error List sub-section.

Click to return to document contents.

Or press {Alt Left Arrow} to return to previous text.

_________________________

Security
a section of the
Embedding And Running AxleBase chapter



Address : jragan.com/axledoc_1.htm#20.70.00
-- . --

( Scroll down for security sub-sections.)

( Axiom : Any software-based security system can be defeated. )

-- . --

End of the Security section header.

Click to return to document contents.

Or press {Alt Left Arrow} to return to previous text.

|-------------------|

Introduction
a sub-section of the
Security section



Address : jragan.com/axledoc_1.htm#20.70.05
-- . --

AxleBase security is designed to be:
      Unobtrusive.
      Multi-level.
      Segmented.
      Very tight.

It is unobtrusive because, unlike the big-name brands (I have programmed against Oracle, MS SQL Server, MySql, etc. etc.), AxleBase does not force the use of security. A new AxleBase installation requires no security configuration, no passwords, no user setup, etc. Tables can be read as soon as they are created. However, it is possible to design and implement an extremely tight and complex security structure for an installation.

Security features are effective when the host is a database server. For example, password access means little when somebody can locally access the password file. By restricting access to remote connections, the database server completes the security.

Security in any kind of computer system is a reptilian nightmare for administrators, engineers, and users. That is sometimes especially so in an advanced AxleBase installation, so security defaults to off upon installation. The "DBA" can then begin turning on security as he learns and as needed in the installation.

AxleBase offers basic security at three levels that are controlled by the DBA.
      Domain
      Database
      Table
      Access to each level is controlled by the level above it.
      The domain is the database domain. Every AxleBase database is created inside a database domain and can be opened only through its domain. An installation may have any number of domains and each domain may contain any number of databases.

Basic AxleBase security uses an extended crud model. (See "AxleBase Lock Granularity") Crud permissions are applicable at all three levels. After security is turned on, every permission for every object defaults to "no".

Enabling security also enables the passthrough control, which is separate from crud controls. Passthrough access can be controlled by name and password at the domain level and at the database level. For example, if access is restricted at the domain level, then the databases in that domain can be accessed only by user name and password at the domain level before encountering the database passthrough controls.

Basic security automatically extends with system expansion into an axsys Super-System. Whether security is turned on before or after system distribution, the extended system is entirely subject to the DBA's security administration. If it is turned on after distribution, then the ReloadNode command can tell all nodes to reload all node and system configurations from disk.

The administration of basic security remains the same for a super-system. However, the distribution raises the internal complexity, and the DBA must understand how the distribution model affects each type of node. Each node is subject to control by parts of the security of various levels and that control varies by node type. (See the "Distributed Database Manager" section of the "Advanced Topics" chapter on page 3 for additional discussion of this topic.)

-- . --

End of the Security Introduction sub-section.

Click to return to document contents.

Or press {Alt Left Arrow} to return to previous text.

|-------------------|

Additional Security
a sub-section of the
Security section



Address : jragan.com/axledoc_1.htm#20.70.07
-- . --

The following are part of the AxleBase security suite. These are separate because they are not members of the AxleBase canonical security sub-system. Some of them even perform duties in addition to security. But they can provide powerful security functions for the database administrator.

The "Authenticate" directive.

The "Comm Authenticate" database, domain, and table attribute changes.

The "Encrypt" command.

The "Decrypt" command.

The "SetVectorEncryption" toggle for the current Vector.

The "Audit Trail" database configuration provides evidence of malevolent activity.

The "Deny SQL Updates " configuration.
      This over-rides security permissions by setting a toggle to protect "VLT"s. When it is on, the data in the database cannot be updated by anybody. No other command or setting can over-ride this.

The "Deny DDL" configuration.
      See the above note.

The "Comm Use Syslink" configuration.

The "Comm Encrypt Envelope" configuration.

The "Comm Hide Error" configuration.

The "Dataset Size Limit" directive. Prevents malicious queries.

The "Hide Security Stops" configuration.
      Prevents malicious probes.

The "Log Toggle" configuration.
      Collects activity records on an entire database.

-- . --

End of the Additional Security sub-section.

Click to return to document contents.

Or press {Alt Left Arrow} to return to previous text.

|-------------------|

Security Activation
a sub-section of the
Security section



Address : jragan.com/axledoc_1.htm#20.70.10
-- . --

AxleBase installs with security turned off. When he creates a domain or database, the created object defaults to open to all access.

Toggle :
      The security toggle is the password for domains and databases.
          On : Assigning a password turns security on.
          Off : Removing all passwords turns it off.

If a database has a master password, then access is restricted only for that database and for that entire database.

Access can be restricted for the entire domain by setting a password on the domain. If a password is set on the domain and no database in the domain has a password, then entry into the domain will permit unlimited access to all databases in the domain.

The "AlterDomainAttribute" and the "AlterDatabaseAttribute" commands are used to set passwords. The password parameter in the "Configuration" chapter has guidance and examples.

If that were all of the security, then security would be a state of all or nothing. But finer granularity is provided by the Grant and Revoke commands. (See GRANT and REVOKE in the API chapter.)