"Security" :
      After security is activated, this command requires :
      update permission at the domain level or
      update permission at the database level.

See Also:
      The ShowLocks command, the Lock Timeout section of the Configuration chapter, and the "System Lock Design" section.

Return expected:   Nothing.
Return on error :   "Error" message.

Example placing an exclusive lock on the current database:
sReturn = oMgr.LockObject ( " database" , "x " )
Example uses sReturn to catch error returns.

Example removing the previous lock:
sReturn = oMgr.LockObject ( "database" , "x" )
Example uses sReturn to catch error returns.

Example removing all locks:
sReturn = oMgr.LockObject ( "database" , "" )
Example uses sReturn to catch error returns.

Example locking the current domain:
sReturn = oMgr.LockObject ( " domain" , "x" )
Example uses sReturn to catch error returns.

-- . --

End of the LockObject sub-section.

Click to return to document contents.

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

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

MoveObject
a sub-section of the
Manager Object section



Address: jragan.com/axledoc_2.htm#70.43.55
-- . --
^

This advanced technology has been temporarily

moved off line during the documentation editing.

This command will move the specified objects and then update the system tables.

-- . --

End of the MoveObject sub-section.

Click to return to document contents.

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

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

NetworkScan
a sub-section of the
Manager Object section



Address: jragan.com/axledoc_2.htm#70.43.60

last update 20230504
-- . --

Syntax:
oManagerObject.NetworkScan [ returnToggle [ , tableName ] ]

This utility is designed for "VLDB" operations and will not usually be needed for ordinary databases.

A database must be open before execution. The network is defined by the database; before beginning cyclic operation, the utility reads the entire database to find the locations that are used by the database.

This command is not designed to replace the network administrator's tools, but it can identify potential problems for database operations. Such problems are frequently of little or no interest to the professional network administrator.

It is designed to be run in a cyclical loop. A pause between loops is recommended. The recommended procedure is to dedicate an "Instance" to running it. Since it is intense, the "YieldProcessor" should be set to yes so that it can be stopped.

Each time that it cycles, it checks the validity of all locations in the database. If the optional TableName is used, then only that table is checked. Otherwise, it checks all tables. (If that optional parameter is passed, then the returnToggle must also be passed.)

ReturnToggle :
      Optional.
      The default is for the output to go into the log.
      If ReturnToggle is "yes", output will also be returned.
      Either logging must be on or ReturnToggle must be "yes".

If run interactively, an offline computer or network segment will cause each internal operation to take up to a minute. If the table has many segments on that faulty infrastructure, the report can take a very long time to return.

More discussion of operation and usage may be found in the Axsys State Assessment sub-section of the Advanced Topics chapter. This command is not interchangeable with the ShowHealth command.

Universalization :
      The report has not yet been completely formatted for unattended systems.

"Security" :
      After security is activated, this command requires database execute or owner permission.

See also: "ShowHealth" and "ScanSegments".

Return expected:   Nothing unless a return is requested.
Return on error :   "Error" message.

Example:
sReturn = oMgr.NetworkScan ( " no, t_log" )
Example uses sReturn to catch error returns.

-- . --

End of the NetworkScan sub-section.

Click to return to document contents.

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

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

OpenDatabase
a sub-section of the
Manager Object section



Address: jragan.com/axledoc_2.htm#70.43.65
-- . --

Syntax:
oManagerObject.OpenDatabase databaseName [ , userId [ , userPassword [ , databasePassword ] ] ]

Opens a connection to the database. If the database does not exist, a trappable error message is returned. (The existence of a database may first be determined with the ShowDatabaseCatalogue command.)

The domain must be opened before one of its databases can be opened.

A database does not need to be closed before opening a new one. If a database is open when the command is received, the "Manager" object will close it and clean up before attempting to open the new one. If the new one fails, no database will be open. Note that the developer must consider any dependent data "Vector" objects.

If the database is already open, the object will be initialized and the database will be re-opened.

Password :
      Optional apostrophe parameter delimiters may be used with the password option when AxleBase might otherwise not accept the literal string of characters. For example, leading spaces would be dropped by AxleBase, but if the string is inside apostrophe delimiters, then leading spaces are protected.

"Error"s :
      Some errors are so serious that the open must be halted and an error returned. That situation can be rectified only by a restore from backups.
      Otherwise, it will attempt to proceed to completion and an error list will then be returned. In that case, operation should not continue; the host should handle the returned errors or pass them on to the user and halt.

"Security" :
      After security is activated, this will require pass-through permission.

See also: CloseDatabase, ShowDatabaseCatalogue,
      See also the domain discussion in "The Database Domain" of the "Embedding And Running AxleBase" chapter.)

Return expected:   Nothing.
Return on error :   Error message.

Example:
sReturn = oMgr.OpenDatabase ( "DEMO" )
Example uses sReturn to catch error returns.

Example:
sReturn = oMgr.OpenDatabase ( "DEMO" , , , mysecrete )
Example uses sReturn to catch error returns.

Example:
sReturn = oMgr.OpenDatabase("DEMO" , me , mypassword , mysecrete )
Example uses sReturn to catch error returns.

-- . --

End of the OpenDatabase sub-section.

Click to return to document contents.

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

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

OpenDomain
a sub-section of the
Manager Object section



Address: jragan.com/axledoc_2.htm#70.43.70
-- . --

Syntax:
oManagerObject.OpenDomain domain openString

Purpose :
      A domain controls a group of databases.
      It must be opened before its databases can be opened.
      Its databases can be located anywhere on the network.

The open string is a string of parameters that define the desired connection. The string is nearly freeform. The sequence of parameters, the letter case, and spacing are ignored. The string may consist of only those parameters that are needed. Parameters with empty values may be included without detriment. If a value is not needed for a connection, unlike most commands, the parameter may be entirely omitted for this command.

Each parameter consists of four elements; the name, the equal sign, the value, and the closing semicolon. (name=value;) The parameter value is not required unless the parameter is required (name=;), but of course, it may be entirely omitted in that case if desired.

domain :
      This parameter is required in all cases.
      It is the location and/or name of a domain.
      It opens a domain or creates and opens a new one.
      Caution. Sloppy habits can create many unwanted domains.
      This parameter is designed for flexibility.
      A domain may be located anywhere by specifying a path.
      If a path is specified, then it must be the complete path.
      The final directory will be the name of the domain.
      The name alone may be given.
      If only the name is used, then exclude slashes.
      A name only will place it under the app in \db\.
      AxleBase will accept a drive letter or a "UNC".
        domain = value ;

UserInstanceId :
      This is used for infrastructure debugging and for error corrections, but not by security. In corporate domains, this is usually the user's domain login, but can be any string, and perhaps the host software should supply it to insure that it is accurate.
        userInstanceId = value ;

UserLocation :
      This is used for infrastructure debugging and for error corrections, but not by security. This is usually the computer or workstation identification, but can be any locator string that is recognizable by the "DBA", so perhaps the host software should supply it.
        userLocation = value ;

UserDomainId :
      The user's domain-level login name if security is active at that level.
        userDomainId = value ;

UserDomainPassword :
      The user's domain-level password if security is active at that level.
        userDomainPassword = value ;

DomainPassword :
      The domain can be assigned its own password.
        userDomainPassword = value ;

Create :
      Value: Yes, no, or an empty string.
      Default: No.
      Value is evaluated if the domain is not found.
      Yes will create the domain if it is not found.
      Indescriminate use can clutter a disk with unused domains.
      Caution: Will clean existing location of any files if yes.
        create = value ;

ConnectionString :
      A ConnectionString command can be used instead of open.
      The domain and database must exist.
      Its connection string will include this and other commands.
      It will open the domain and its database in one step.
      (See the ConnectionString command in this chapter.)

The AxleBase system is designed to support any number of database domains in an installation. Each domain can control any number of databases.

"Error"s :
      Some errors are so serious that the opening must be halted and an error returned. That situation can be rectified only by a restore from backups.
      Otherwise, it will attempt to proceed to completion and an error will then be returned. In that case, operation should not continue; the host should handle the returned error or pass it on to the user and halt.

"Security" :
      Security cannot be checked if a domain is not open.
      If a domain is open and security is activated :
        Pass-through permission is required.
        Owner permission required to create a new domain.

See also: DropDomain; CreateDatabase; ConnectionString
      See also the domain discussion in "The Database Domain" of the "Embedding And Running AxleBase" chapter.)

Return expected:   Nothing.
Return on error :   Error message.

Example:
sReturn = oMgr.OpenDomain ( domain = c:\program files\AxHandle\db\demoDom ; create = yes;)
Example uses sReturn to catch error returns.
That example will open or create the domain master in
c:\program files\AxHandle\db\demoDom

Example:
sReturn = oMgr.OpenDomain ( domain = demoDom ;)
Name and location will be the same as the preceding example.

Example:
sReturn = oMgr.OpenDomain ( domain = c:\program files\AxHandle\db\demoDom ; userDomainId = me; userDomainPassword = mypassword ; )
Example uses sReturn to catch error returns.

Example:
sReturn = oMgr.OpenDomain ( domain = c:\program files\AxHandle\db\demoDom ; userDomainPassword = masterfulpword ; ")
Example uses sReturn to catch error returns.

-- . --

End of the OpenDomain sub-section.

Click to return to document contents.

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

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

Purge
a sub-section of the
Manager Object section



Address: jragan.com/axledoc_2.htm#70.43.75
-- . --
^

This advanced technology, with its "VLDB" Addendum,

has been temporarily moved off line during the

documentation editing.

This utility removes deleted and obsolete rows from the database. (Although some hide it, all brands of database managers must purge their databases. This one is designed to handle VLT's.)

-- . --

End of the Purge sub-section.

Click to return to document contents.

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

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

RestoreBackup
a sub-section of the
Manager Object section



Address: jragan.com/axledoc_2.htm#70.43.85
-- . --

Syntax:
oManagerObject.RestoreBackup backupLocation [ , object ]

Performs a restoration of a table, database, or domain from the specified location. All of the data in the object will be replaced by the archived data. All changes and object creations since the backup will be lost.

"TestMode" :
      If there is concern about system stability, first turn on TestMode. As long as it is on, commands will run up to the commit point and exit without committing. That allows errors to stop the process and return error messages. (This command cannot use an "Appendix" to test.)

Execution :
      Find the parameters that you will use.
      Execute AxleBase to load an AxleBase "Instance".
      Use the instance to open a "Manager" object to control the following commands. See the "Manager Object Interface Introduction". As shown by the example, the manager object will execute the following commands.
      Use the "OpenDomain" command to open the database domain that will be used.
      Use the "OpenDatabase" command to open the database.
      Execute this "Restore" command.
      Check for error returns after each step.

A dropped table will not be recognized as a valid table and cannot be restored. Re-create the table, ignoring indexing, and it can then be restored from the archive.

BackupLocation :
      This is the complete path to the backup including the final database or domain directory name. The required location may not be the location to which you made the backup. For example, a generational backup inserts a time-stamped directory into the path.

Domain :
      Caution! Before attempting to restore a domain, insure that no database was created or dropped since the last backup. If a database was created after the last backup, a domain restore will render it inaccessible. If a database was dropped after the last backup, a domain restore will render the domain inconsistent.

Object :
      Object is optional.
      It may be blank, "database", "domain", or a table name.
      Blank or "database" will restore the entire database.
      The keyword "domain" will restore a domain backup.
      A table name will restore only that table from the backup.

Lock Requirement :
      If the object is a domain, then the domain must be locked exclusively. Other objects require an exclusive database lock. (See "LockObject" command.) Before setting the lock, insure that the lock timeout will allow enough time for you to start the operation. The database lock is required even for a single table since the system cannot know the use or importance of that table to local operations.
      The lock will be removed by the disconnect. See below.

Disconnect :
      After restoration, the system will close the database connection to insure re-initialization of all objects and values. If the object is a domain, then it, too, will be initialized.

Archive Validity :
      AxleBase cannot recognize the validity state of an archive. He performs superficial checks before beginning, but it is possible to wipe out a table or database by restoring from a corrupted backup.

Restart :
      Do not interrupt a restore.
      Interruption of a restore will result in a corrupted object.
      If a connection can be made after an interruption, there is a possibility that a restore restart may succeed.
      If the interrupted restore cannot be consumated, then the object was corrupted by the interruption and the restore must be done by manually copying the files.

"Security" :
      After security is activated, this command requires database execute or owner permission.

See also: Backup;

Return expected:   Nothing.
Return on error :   "Error" message.

Example restoring a database:
sReturn = oMgr.RestoreBackup "c:\backup_demo_seg\demo_seg\"
Example uses sReturn to catch error returns.

Example restoring a domain:
sReturn = oMgr.RestoreBackup "c:\backup\demodom\ , domain "
Example uses sReturn to catch error returns.

Example restoring a single table named t_log:
sReturn = oMgr.RestoreBackup "c:\backup\demo_seg\ , t_log "
Example uses sReturn to catch error returns.

The following comments and instructions do not apply to normal databases.

Although the Backup command provides the ability to address requirements of a distributed database, the RestoreBackup does not. That increases the solidity for distributed operations by insuring the backup of the primary files. Distributed table segments must be copied manually.

-- . --

End of the RestoreBackup sub-section.

Click to return to document contents.

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

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

Revoke
a sub-section of the
Manager Object section



Address: jragan.com/axledoc_2.htm#70.43.90
-- . --

Syntax:
oManagerObject.REVOKE accessType
ON objectType objectName
FROM userName
[ ; appendix ( options ) ] )

The Revoke command revokes the ability to access, use, or perform operations on specified objects.

AccessType :
      Any combination of the keywords ALL, SELECT, DELETE, INSERT, UPDATE, or EXECUTE. If the keyword ALL or an asterisk is used, then it revokes all of the access priviledges.

ObjectType :
      Any combination of the keywords DOMAIN, DATABASE, TABLE, or JOB. The keyword all and the asterisk will be applied only to objects in the database and not to domains and not to databases.

The keyword ALL or an asterisk may be used in the FROM clause. When used there, the revoke is applied to all entities.

The object name:
      Required. The keyword ALL may be used for the object name. If the keyword ALL is used, then the command is applied to all objects of the specified type.

This is a security component. As discussed in the Security section of the Embedding And Running AxleBase chapter, this feature is effective only when the host is a server such as a web server or an odbc server that limits activity to remote connections.

Of significance is the fact that AxleBase requires no access security until security is turned on.

Test :
      A test may be specified in the "Appendix" clause. It will run the command up to execution, and then exit. See the Test option sub-section.

"Security" :
      After security is activated, this command requires :
      update permission at the domain level for updates of database and domain security, and
      update permission at the database level for others.

AxleBase deviates from the standard to allow the command to cover domains and databases as well as tables.

See also: Grant, ShowPermissions and AxleBase Lock Granularity).

See also "Turning On Security" in the Embedding And Running AxleBase chapter.

Return expected:   Nothing.
Return on error :   "Error" message.

Example:
sReturn = oMgr.Revoke ( " insert on domain demodom from allen " )
Example uses sReturn to catch error returns.

Example that revokes all of Mary's access within a database:
sReturn = oMgr.Revoke ( " all on all all from Mary " )
Example uses sReturn to catch error returns.

Example locking Mary out of every database:
sReturn = oMgr.Revoke ( " all on database all from Mary " )
Example uses sReturn to catch error returns.

Example clearing all rights within a database:
sReturn = oMgr.Revoke ( " all on all all from all " )
Example uses sReturn to catch error returns.

-- . --

End of the Revoke sub-section.

Click to return to document contents.

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

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

RunJob
a sub-section of the
Manager Object section



Address: jragan.com/axledoc_2.htm#70.43.93
-- . --

Syntax:
oManagerObject.RunJob JobName

Run a job that has previously been saved.

The "ShowJobs" command will return a list of jobs that have been saved in the database.

Execution :
      Execute AxleBase to load an AxleBase Instance".
      Use the instance to open a "Manager" object to control the following commands. See the "Manager Object Interface Introduction". As shown by the example, the manager object will execute the following commands.
      Use the "OpenDomain" command to open the database domain that will be used.
      Use the "OpenDatabase" command to open the database.
      Use the "ShowJobs" command if needed.
      Execute the "RunJob" command.
      Check for error returns after each step.

See also: CreateJob, DropJob, ShowJobs.

Return expected:   Nothing.
Return on error :   "Error" message.

Example:
sReturn = oMgr.RunJob ( "myJobName" )
Example uses sReturn to catch error returns.

-- . --

End of the RunJob sub-section.

Click to return to document contents.

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

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

ScanSegments
a sub-section of the
Manager Object section



Address: jragan.com/axledoc_2.htm#70.45.05
-- . --
^

This advanced technology has been temporarily

moved off line during the documentation editing.

Designed to support high speed, always available, databases.

This is an unattended utility that cycles continually through a large table until commanded to stop. It watches for loss of data files in the table. See also the "Data Failover" attribute and the "Data Failover By All" in the "Configuration" chapter.

-- . --

End of the ScanSegments sub-section.

Click to return to document contents.

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

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

ShareDatabase
a sub-section of the
Manager Object section



Address: jragan.com/axledoc_2.htm#70.45.10

Completed and expanded 20220928
Updated 20221013
-- . --

Syntax:
oManagerObject.ShareDatabase ServerName, Drive

Purpose:
      Where creating a server to host AxleBase is not feasible, this command allows a database to be shared on a network after it is created.
      Install an instance of AxleBase on each remote computer that will use the shared database.
      Without a server, a database cannot be used remotely, because computer operating systems become confused by paths. For example, it might receive a path such as "c:\database\", which is where the database is located, but every computer has its own "c:" drive. Also, the flexibility of AxleBase makes matters even worse because it allows many objects in each database to be relocated by the "DBA" to other computers and locations on the network to improve performance.
      This utility translates the various locations that are stored inside a database into "UNC"(universal naming convention) forms that can be used universally by any machine that can access the database computer. It also updates the database's domain.
      ( If AxleBase and its databases are on a shared computer and drive from the beginning, then your databases may already be shared, but they must be reshared if moved. If this command is run anyway, AxleBase will recognize the redundant command and compensate.)

Path Construct :
      AxleBase expects all paths to be either standard local paths in the form of
      c:\directory\
      or in the shared "UNC" form of
      \\serverName\sharedDriveName\directory\
      See "Storage Location" coverage on the nomenclature document.

System Refusal:
      The system will abort the command for the following reasons.
      "System Design Limits":
      To protect your data, this command will halt and return an error message if any object in the database is bigger than 2 gigabytes. If a table is planned to grow to a large size, you should not share its database. Its share cannot be altered after exceeding 2 gigabytes.
      System Object Relocations :
      AxleBase allows the "DBA" to permanently relocate system objects for performance. Be sure that all locations in the database have been left in the default database locations. If you run the share command against a relocation, you may damage your database.
      "Axsys Super-System" :
      An axsys super-system will refuse to run this command. Stop the super-system, clear users, open the database in a standard database configuration, and run the command again.

Unattended Processes :
      Before running this command, stop and unload all unattended and autonomic processes such as the "ScanSegments" utility.

Safeties: :
      Lock:
          Before beginning :
          Clear all users from the database.
          The ShareDatabase utility will run the "LockObject" command to place an exclusive-use lock on the database before beginning operation. If it cannot obtain the database lock, it will halt, clear the system, and give you an error report.
      TestMode:
      (Refer to "TestMode" usage.)
      If there is concern about your command or about the system's stability, try running it first with "TestMode" activated in your current "Instance". As long as the "TestMode" toggle is on in that instance, commands will run up to the commit point and exit without committing. "TestMode" allows errors to stop the process and return error messages without risking commit execution.
      After you debug the command, test thoroughly. If there are no errors, turn off the test toggle, and run the command to update the database. (The "ShareDatabase" command cannot use the "Appendix" capsule for testing.)
      Backup:
      When using a command that affects the entire database, such as the "Share" command, consider first making a backup of the entire database.
      (Refer to the "Backup" command.)
      When the builder is working on a database, if it has no large table, and no objects have been relocated, he sometimes just drags a copy of the entire database directory to another drive. If the share command works without error and the database tests well, he is done and the backup copy can be deleted. If the operation fails he can delete the entire database directory and drag a copy back from the backup.
      "Attributes":
      Database attributes now include a "shared to network" attribute. Run the "ShowDatabaseAttributes" command to see it. Unlike other AxleBase attributes, this one can be altered only by this "ShareDatabase" command due to its complexity.

Before Execution :
      - Your system administrator will need to share your disk drive to your network. He can then tell you the disk share names and your computer's network name.
      - Ask him to use the shared "UNC" path names as shown in the "UNC" section of the "Nomenclature" document. For example, the database may be located on the c: drive of a computer named bus3, so you will share the path as
      \\bus3\c\AxleBase\dbname
or something similar,
instead of the usual
      c:\AxleBase\dbname
Correctly running the "ShareDatabase" command will change all of the paths within the database to the shared names to allow remote use of the database. The remote user will pass the new UNC path and name to his AxleBase "Instance" to operate the remote database.

Execution :
      ( Your organization may have created an app for you similar to "AxHandle" that runs the following operations from a push button.)
      Find the parameters that you will use.
      Execute AxleBase to load an AxleBase "Instance".
      In that instance, open a "Manager" object. See the "Manager Object Interface Introduction". You can use the Manager object to execute the following commands.
      Execute the "OpenDatabase" command to open the database that will be shared.
      Execute the "ShareDatabase" command.
      Check for error returns after each step.

AxHandle :
      "AxHandle" may simplify things for you.:
      ( There is more coverage of AxHandle in the "AxHandle" section and its following sub-sections.)
      - Highlight the "Connection String" selection. Press the "parameters" button and the required parameters will be displayed. Other optional "Connection String" parameters are covered in the documentation. Determine the needed information, enter it as a character string, and press the "do it" button.
      - When a connection is successful, AxHandle saves it. In the future, press the "open db" button to display all stored data connections. Double click the one that you created, or highlight it and press the "do it" button
      - After the database is open, to see its current attributes, such as its paths, highlight the "ShowDatabaseAttributes" in "AxHandle"s command window, and press the "do it" button.
      - Highlight the "ShareDatabase" command in the command window. Press the "Show Parameters" button to display the command's parameters.
      - Enter the correct values in the parameters window, and press the "do it" button.

Security :
      (Refer to the "Security" section and its following sub-sections.)
      The use of this "ShareDatabase" command is not recommended because it opens the database and its domain to everybody on your network. It bypasses much of the AxleBase security sub-system.
      Recommend that the "VPN" be disabled unless the system's "DBA" is professionally advanced.
      If the "DBA" has activated security in the database, then this command requires that you have update permission at the database level.
      The "Share" command also requires that the DDL (Data Definition Language) toggle be on. Execution will fail with an error report if the "DBA" has turned off the DDL permission.
      For extreme security hardening, AxleBase allows the "DBA" to turn off error returns in several error domains. Before executing this command, insure that the he has not disabled any error returns in the security sub-system. If the system cannot return security errors, this command can cause damage without user notification. Be sure to tell him when you are done, so he can reconfigure security.
      After successful completion of the command, subsequent remote access will be watched by the security sub-system.

Database Domain :
      When this ShareDatabase command was completed in 2022, it had been redesigned in several areas including the database domain. This command now also alters the database's domain.

See Also :
      The configurable "Shared" table attribute, and
      the unconfigurable "Shared Database" attribute.

Return expected:   None.
Return on error :   "Error" message.

Example:
sReturn = oMgr.ShareDatabase ServerName, SharedDrive
Example uses sReturn to catch error returns.
Note that the server's name in this case is "ServerName", and the name of the shared drive is actually "SharedDrive".
Example:
sReturn = oMgr.ShareDatabase monsoon, c

-- . --

End of the ShareDatabase sub-section.

Click to return to document contents.

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

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

ShareDomain
a sub-section of the
Manager Object section



Address: jragan.com/axledoc_2.htm#70.45.15
-- . --

Syntax:
oManagerObject.ShareDomain ServerName, SharedDrive

( Under construction.
    October 2022
    Decision is made to reactivate, study, and expand the "ShareDomain" command to maintain the distributed database and distributed system control features and flexibility.

Purpose:
      For those who are unable to build a server to host AxleBase, this command allows a domain to be shared across a network after it is created. To share each of the databases in the domain, the "ShareDatabase" command will be used. The "ShareDatabase" sub-section has additional information.

"Security" :
      The use of this command is not recommended, because it opens the database domain to others on the network.

The domain must be open when the command is issued to help you insure that you are updating the correct domain.

"TestMode" :
      If there is concern about system stability, first turn on TestMode in the local AxleBase instance. As long as it is on, commands will run up to the commit point and exit without committing. That will allow errors to stop the process and return error messages. (This command can use only the "Manager" test, and cannot use an "Appendix" envelope to test.)

Execution :
      Find the parameters that you will use.
      Execute AxleBase to load an AxleBase "Instance".
      Use the instance to open a "Manager" object to control the following commands. See the "Manager Object Interface Introduction". As shown by the example, the manager object can execute the following commands.
      Use the "OpenDatabase" command to open the database that will be shared.
      Execute the "ShareDatabase" command.
      Check for error returns after each step.

Valid paths are required for all of the parameters. Connections will fail if any path cannot be used from a remote workstation. Therefore, all of the parameters must be shared paths. For example, the domain may exist on the local drive in the path, c:\db\domain\, and the share parameter may be a share name such as \\server4\server4c\db\data\ .

This command may be re-issued at any time to update shared locations.

"Security" :
      If security has been activated, then this command will require update permission at the domain level.
      Subsequent remote access will be subject to security screening.

CAUTION :
      Check parameters before entering. The parameters are checked by AxleBase, but it is possible to submit a valid path that is not valid for the intended object. If, for example, the entered index path is for a different database, the system cannot know that. Such an error can produce extremely interesting and unwelcome events, and can be fixed only by a manual edit of the system files in a text editor.

See also: ShareDatabase"
      See also the domain discussion in "The Database Domain" of the "Embedding And Running AxleBase" chapter.)

( Do not confuse this command with the configurable "Shared" table attribute.

Return expected:   None.
Return on error :   "Error" message.

Example:
sReturn = oMgr.ShareDomain ( serverName , sharedDrive)
Example uses sReturn to catch error returns.

-- . --

End of the ShareDomain sub-section.

Click to return to document contents.

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

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

ShowColumns
a sub-section of the
Manager Object section



Address: jragan.com/axledoc_2.htm#70.45.27
-- . --

Syntax:
sReturn = oManagerObject.ShowColumns [ tableName [ , NamesOnly ] ]

Returns descriptions of all columns in the specified object.

TableName :
      The optional tableName parameter will limit the return to those columns that are in that table.

Report Structure :
      This report has header and footer lines.
      The header and footer identify the report uniquely.
      A header line names the elements listed below.
      The body consists of column descriptions.
      Each description consists of elements.
      Elements are separated by a comma and a space.
      The elements are :
            the literal "** column description"
            tableName
            columnName
            columnDataType
            ordinality
            start
            width
            default
            lock
            lockProc
            nullable

NamesOnly :
      Optional parameter is "Boolean".
      A "yes" will return only a list of the names.
      Each will be prefixed by chr 13 and chr 10.
      For the entire database :
          Each will be the table and column name.
          Separated by a period.
      For a specified table :
          Each will be the column name.

Before the command is issued, the domain and the database must be open; i.e., a connection must be made.

Universalization :
      This report has been formatted for understanding by people and by unattended systems.

"Security" :
      After security is activated, this requires read permission at the database level.

See also: ShowTable.

Return expected:   Character string.
Return on error :   "Error" message.

Example:
sReturn = oMgr.ShowColumns
sReturn will contain either the report for the entire database or an error message.

Example:
sReturn = oMgr.ShowColumns , , yes
sReturn will contain either the column names only for the entire database or an error message.

Example:
sReturn = oMgr.ShowColumns , t_log , yes
sReturn will contain either the column names only for the t_log table or an error message.

Example:
sReturn = oMgr.ShowColumns
Following is the column report for the demo_citizen database that AxHandle creates.

Report: Database Columns
Report ID: boFilPYuffddegih5qTMNKSGQiEDLP
DateTime: 2022080816325241
Database: demo_citizen
kTNMTcJJffdfeded7nKk2GwE17KGYT

** report line label, table, column, datatype, ordinality, start, width, default, lock, holder, nullable

** column, T_WATCHER, citizen_id, integer, 2, 2, 20, , , , null
** column, T_WATCHER, unit_id, integer, 3, 22, 20, , , , null
** column, T_WATCHER, officer_id, integer, 4, 42, 20, , , , null
** column, T_WATCHER, last_update, datetime, 5, 62, 16, , , , null
** column, T_WATCHER, updater, string, 6, 78, 20, , , , null

** column, T_ATTITUDE_SCALE, attitude, integer, 2, 2, 20, , , , null
** column, T_ATTITUDE_SCALE, description, string, 3, 22, 70, , , , null
** column, T_ATTITUDE_SCALE, last_update, datetime, 4, 92, 16, , , , null
** column, T_ATTITUDE_SCALE, updater, string, 5, 108, 20, , , , null


** column, T_CITIZEN, citizen_id, serial, 2, 2, 20, , , , null
** column, T_CITIZEN, name_first, string, 3, 22, 30, , , , null
** column, T_CITIZEN, name_last, string, 4, 52, 30, , , , null
** column, T_CITIZEN, licensed_breeder, boolean, 5, 82, 1, , , , null
** column, T_CITIZEN, d_o_b, datetime, 6, 83, 16, , , , null
** column, T_CITIZEN, d_o_d, datetime, 7, 99, 16, , , , null
** column, T_CITIZEN, assigned_residence, numeric, 8, 115, 20, , , , null
** column, T_CITIZEN, occupation_cat, string, 9, 135, 10, , , , null
** column, T_CITIZEN, occupation_sub, string, 10, 145, 10, , , , null
** column, T_CITIZEN, education_cat, string, 11, 155, 3, , , , null
** column, T_CITIZEN, education_level, string, 12, 158, 3, , , , null
** column, T_CITIZEN, intelligence, numeric, 13, 161, 20, , , , null
** column, T_CITIZEN, last_update, datetime, 14, 181, 16, , , , null
** column, T_CITIZEN, updater, string, 15, 197, 20, , , , null


** column, T_CITIZEN_STATUS, citizen_id, serial, 2, 2, 20, , , , null
** column, T_CITIZEN_STATUS, location, string, 3, 22, 16, , , , null
** column, T_CITIZEN_STATUS, status, string, 4, 38, 2, , , , null
** column, T_CITIZEN_STATUS, watch_type, string, 5, 40, 2, , , , null
** column, T_CITIZEN_STATUS, flag, boolean, 6, 42, 1, , , , null
** column, T_CITIZEN_STATUS, last_update, datetime, 7, 43, 16, , , , null
** column, T_CITIZEN_STATUS, updater, string, 8, 59, 20, , , , null


** column, T_COUNTRY_CODE, country, string, 2, 2, 2, , , , null
** column, T_COUNTRY_CODE, internet_code, string, 3, 4, 3, , , , null
** column, T_COUNTRY_CODE, country_name, string, 4, 7, 50, , , , null
** column, T_COUNTRY_CODE, description, string, 5, 57, 100, , , , null
** column, T_COUNTRY_CODE, last_update, datetime, 6, 157, 16, , , , null
** column, T_COUNTRY_CODE, updater, string, 7, 173, 20, , , , null


** column, T_DESCRIPTORS, citizen_id, integer, 2, 2, 20, , , , null
** column, T_DESCRIPTORS, dna_chart, blob, 3, 22, 100, , , , null
** column, T_DESCRIPTORS, face_hologram, blob, 4, 122, 100, , , , null
** column, T_DESCRIPTORS, hologram_date, datetime, 5, 222, 16, , , , null
** column, T_DESCRIPTORS, holographer, integer, 6, 238, 20, , , , null
** column, T_DESCRIPTORS, brain_wave_print, blob, 7, 258, 100, , , , null
** column, T_DESCRIPTORS, brain_wave, datetime, 8, 358, 16, , , , null
** column, T_DESCRIPTORS, brain_scanner, integer, 9, 374, 20, , , , null
** column, T_DESCRIPTORS, thought_scan_analysis, blob, 10, 394, 100, , , , null
** column, T_DESCRIPTORS, thought_scan_date, datetime, 11, 494, 16, , , , null
** column, T_DESCRIPTORS, thought_analyst, integer, 12, 510, 20, , , , null

** column, T_EMPLOYMENT_HISTORY, citizen_id, integer, 2, 2, 20, , , , null
** column, T_EMPLOYMENT_HISTORY, permit, integer, 3, 22, 20, , , , null
** column, T_EMPLOYMENT_HISTORY, start, datetime, 4, 42, 16, , , , null
** column, T_EMPLOYMENT_HISTORY, end, datetime, 5, 58, 16, , , , null
** column, T_EMPLOYMENT_HISTORY, employer_id, integer, 6, 74, 20, , , , null
** column, T_EMPLOYMENT_HISTORY, last_update, datetime, 7, 94, 16, , , , null
** column, T_EMPLOYMENT_HISTORY, updater, string, 8, 110, 20, , , , null

** column, T_INTIMATE, citizen_id, integer, 2, 2, 20, , , , null
** column, T_INTIMATE, parent_male, integer, 3, 22, 20, , , , null
** column, T_INTIMATE, parent_female, integer, 4, 42, 20, , , , null
** column, T_INTIMATE, sexual_1, integer, 5, 62, 20, , , , null
** column, T_INTIMATE, sexual_type_1, string, 6, 82, 2, , , , null
** column, T_INTIMATE, sexual_2, integer, 7, 84, 20, , , , null
** column, T_INTIMATE, sexual_type_2, string, 8, 104, 2, , , , null
** column, T_INTIMATE, sexual_3, integer, 9, 106, 20, , , , null
** column, T_INTIMATE, sexual_type_3, string, 10, 126, 2, , , , null
** column, T_INTIMATE, friend_1, integer, 11, 128, 20, , , , null
** column, T_INTIMATE, friend_2, integer, 12, 148, 20, , , , null
** column, T_INTIMATE, friend_3, integer, 13, 168, 20, , , , null
** column, T_INTIMATE, friend_4, integer, 14, 188, 20, , , , null
** column, T_INTIMATE, friend_5, integer, 15, 208, 20, , , , null
** column, T_INTIMATE, friend_6, integer, 16, 228, 20, , , , null
** column, T_INTIMATE, friend_7, integer, 17, 248, 20, , , , null
** column, T_INTIMATE, last_update, datetime, 18, 268, 16, , , , null
** column, T_INTIMATE, updater, string, 19, 284, 20, , , , null

** column, T_INTIMATE_HISTORY, citizen_id, integer, 2, 2, 20, , , , null
** column, T_INTIMATE_HISTORY, date_start, datetime, 3, 22, 16, , , , null
** column, T_INTIMATE_HISTORY, date_end, datetime, 4, 38, 16, , , , null
** column, T_INTIMATE_HISTORY, associate, integer, 5, 54, 20, , , , null
** column, T_INTIMATE_HISTORY, type_associate, string, 6, 74, 2, , , , null
** column, T_INTIMATE_HISTORY, last_update, datetime, 7, 76, 16, , , , null
** column, T_INTIMATE_HISTORY, updater, string, 8, 92, 20, , , , null

** column, T_MARRIAGE_PERMIT, permit, integer, 2, 2, 20, , , , null
** column, T_MARRIAGE_PERMIT, citizen, integer, 3, 22, 20, , , , null
** column, T_MARRIAGE_PERMIT, date_assigned, datetime, 4, 42, 16, , , , null
** column, T_MARRIAGE_PERMIT, approved_by, integer, 5, 58, 20, , , , null
** column, T_MARRIAGE_PERMIT, expiration, datetime, 6, 78, 16, , , , null
** column, T_MARRIAGE_PERMIT, rescinded, datetime, 7, 94, 16, , , , null
** column, T_MARRIAGE_PERMIT, rescinded_by, integer, 8, 110, 20, , , , null
** column, T_MARRIAGE_PERMIT, last_review, datetime, 9, 130, 16, , , , null
** column, T_MARRIAGE_PERMIT, reviewed_by, integer, 10, 146, 20, , , , null
** column, T_MARRIAGE_PERMIT, last_update, datetime, 11, 166, 16, , , , null
** column, T_MARRIAGE_PERMIT, updater, string, 12, 182, 20, , , , null

** column, T_PERSONAL_PERMITS, citizen_id, integer, 2, 2, 20, , , , null
** column, T_PERSONAL_PERMITS, birth, integer, 3, 22, 20, , , , null
** column, T_PERSONAL_PERMITS, employment, integer, 4, 42, 20, , , , null
** column, T_PERSONAL_PERMITS, marriage, integer, 5, 62, 20, , , , null
** column, T_PERSONAL_PERMITS, night_movement, integer, 6, 82, 20, , , , null
** column, T_PERSONAL_PERMITS, residence, integer, 7, 102, 20, , , , null
** column, T_PERSONAL_PERMITS, travel, integer, 8, 122, 20, , , , null
** column, T_PERSONAL_PERMITS, vehicle, integer, 9, 142, 20, , , , null
** column, T_PERSONAL_PERMITS, voter, integer, 10, 162, 20, , , , null
** column, T_PERSONAL_PERMITS, last_update, datetime, 11, 182, 16, , , , null
** column, T_PERSONAL_PERMITS, updater, string, 12, 198, 20, , , , null

** column, T_RESIDENCE, citizen_id, integer, 2, 2, 20, , , , null
** column, T_RESIDENCE, date_assigned, datetime, 3, 22, 16, , , , null
** column, T_RESIDENCE, last_review, datetime, 4, 38, 16, , , , null
** column, T_RESIDENCE, residence_id, integer, 5, 54, 20, , , , null
** column, T_RESIDENCE, coordinates, numeric, 6, 74, 20, , , , null
** column, T_RESIDENCE, country, string, 7, 94, 2, , , , null
** column, T_RESIDENCE, political_unit, string, 8, 96, 50, , , , null
** column, T_RESIDENCE, sub_unit, string, 9, 146, 50, , , , null
** column, T_RESIDENCE, city, string, 10, 196, 50, , , , null
** column, T_RESIDENCE, city_zone, string, 11, 246, 50, , , , null
** column, T_RESIDENCE, street, string, 12, 296, 50, , , , null
** column, T_RESIDENCE, square_feet, numeric, 13, 346, 20, , , , null
** column, T_RESIDENCE, lock_code, string, 14, 366, 50, , , , null
** column, T_RESIDENCE, local_class, string, 15, 416, 10, , , , null
** column, T_RESIDENCE, last_update, datetime, 16, 426, 16, , , , null
** column, T_RESIDENCE, updater, string, 17, 442, 20, , , , null


** column, T_RESIDENCE_HISTORY, citizen_id, integer, 2, 2, 20, , , , null
** column, T_RESIDENCE_HISTORY, date_assigned, datetime, 3, 22, 16, , , , null
** column, T_RESIDENCE_HISTORY, date_vacated, datetime, 4, 38, 16, , , , null
** column, T_RESIDENCE_HISTORY, residence_id, integer, 5, 54, 20, , , , null
** column, T_RESIDENCE_HISTORY, coordinates, numeric, 6, 74, 20, , , , null
** column, T_RESIDENCE_HISTORY, country, string, 7, 94, 2, , , , null
** column, T_RESIDENCE_HISTORY, political_unit, string, 8, 96, 50, , , , null
** column, T_RESIDENCE_HISTORY, sub_unit, string, 9, 146, 50, , , , null
** column, T_RESIDENCE_HISTORY, city, string, 10, 196, 50, , , , null
** column, T_RESIDENCE_HISTORY, city_zone, string, 11, 246, 50, , , , null
** column, T_RESIDENCE_HISTORY, street, string, 12, 296, 50, , , , null
** column, T_RESIDENCE_HISTORY, square_feet, numeric, 13, 346, 20, , , , null
** column, T_RESIDENCE_HISTORY, lock_code, string, 14, 366, 50, , , , null
** column, T_RESIDENCE_HISTORY, local_class, string, 15, 416, 10, , , , null
** column, T_RESIDENCE_HISTORY, last_update, datetime, 16, 426, 16, , , , null
** column, T_RESIDENCE_HISTORY, updater, string, 17, 442, 20, , , , null


** column, T_STATUS_CODE, status, string, 2, 2, 2, , , , null
** column, T_STATUS_CODE, status_name, string, 3, 4, 10, , , , null
** column, T_STATUS_CODE, description, string, 4, 14, 100, , , , null
** column, T_STATUS_CODE, last_update, datetime, 5, 114, 16, , , , null
** column, T_STATUS_CODE, updater, string, 6, 130, 20, , , , null


** column, T_STATUS_HISTORY, citizen_id, integer, 2, 2, 20, , , , null
** column, T_STATUS_HISTORY, start_status, datetime, 3, 22, 16, , , , null
** column, T_STATUS_HISTORY, status, string, 4, 38, 2, , , , null
** column, T_STATUS_HISTORY, watch_type, string, 5, 40, 2, , , , null
** column, T_STATUS_HISTORY, flag, boolean, 6, 42, 1, , , , null
** column, T_STATUS_HISTORY, last_update, datetime, 7, 43, 16, , , , null
** column, T_STATUS_HISTORY, updater, string, 8, 59, 20, , , , null

** column, T_TRAVEL_HISTORY, citizen_id, integer, 2, 2, 20, , , , null
** column, T_TRAVEL_HISTORY, permit, integer, 3, 22, 20, , , , null
** column, T_TRAVEL_HISTORY, start, datetime, 4, 42, 16, , , , null
** column, T_TRAVEL_HISTORY, end, datetime, 5, 58, 16, , , , null
** column, T_TRAVEL_HISTORY, destination, string, 6, 74, 20, , , , null
** column, T_TRAVEL_HISTORY, purpose, string, 7, 94, 20, , , , null
** column, T_TRAVEL_HISTORY, last_update, datetime, 8, 114, 16, , , , null
** column, T_TRAVEL_HISTORY, updater, string, 9, 130, 20, , , , null

** column, T_WATCH_CODE, watch_type, string, 2, 2, 2, , , , null
** column, T_WATCH_CODE, watch_name, string, 3, 4, 10, , , , null
** column, T_WATCH_CODE, description, string, 4, 14, 100, , , , null
** column, T_WATCH_CODE, last_update, datetime, 5, 114, 16, , , , null
** column, T_WATCH_CODE, updater, string, 6, 130, 20, , , , null

End of DB Column Report boFilPYuffddegih5qTMNKSGQiEDLP

-- . --

End of the ShowColumns sub-section.

Click to return to document contents.

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

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

ShowCopyright
a sub-section of the
Manager Object section



Address: jragan.com/axledoc_2.htm#70.45.30
-- . --

Syntax:
oManagerObject.ShowCopyright

Returns the legal copyright.

Any attempt to mask, bypass, alter, alias, camouflage, or qualify either this command or its return, legally revokes the right of the individual and/or organization to use AxleBase and its supporting software, and may precipitate legal consequences.

Return expected:   Copyright notice.
Return on error :   "Error" message.

Example:
sReturn = oMgr.ShowCopyright
sReturn will contain the copyright.

-- . --

End of the ShowCopyright sub-section.

Click to return to document contents.

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

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

ShowCount
a sub-section of the
Manager Object section



Address: jragan.com/axledoc_2.htm#70.45.35
-- . --

Syntax:
oManagerObject.ShowCount objectType

Returns the quantity of the specified objects. The return will be an "Integer", including 0 for none.

Object Type :
      Required.
      Must be one of the following types :
            column
            database
            dataObject
            index
            key
            table
A table's column count may be specified by prefixing column with the table name and a dot.

DataObject :
      If the Manager object is used to create data "Vector" objects, the quantity currently in existence can be determined. See the DataObjectCreate command.

Return expected:   An integer.
Return on error :   "Error" message.

Example:
sReturn = oMgr.ShowCount ( "table" )
sReturn will contain the number of tables or an error message.

-- . --

End of the ShowCount sub-section.

Click to return to document contents.

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

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

ShowDatabase
a sub-section of the
Manager Object section



Address: jragan.com/axledoc_2.htm#70.45.40
-- . --

Syntax:
oManagerObject.ShowDatabase

This report shows the structure of the currently open database by returning its SQL construct. The SQL construct is the series of SQL statements that would be used to create the entire database.
      ( It has been ten or twenty years since creating it, so I do not know, but based on how I work, you might be able to hand it to the AxleBase ExecuteSQL command to create the database.)

Each element of the report is prefixed by an end-of-line. That includes the first one to bypass the zerothe element when arrayed. The structure elements begin with the "create" keyword.

Header, footer, and comments are encapsulated by SQL comment characters.

Universalization :
      This report delivers industry-standard DDL that may or may not be red by people and unattended systems. (Since there are no industry standard embedded comments, it uses the AxleBase comments.)

"Security" :
      After security is activated, this requires read permission at the database level.

See also: ShowDatabaseCatalogue, ShowDatabaseAttributes, ShowTable, ShowTables.

Return expected:   A string of multiple SQL statements.
Return on error :   "Error" message.

Example:
sReturn = oMgr . ShowDatabase

Example:
sReturn = oMgr.ShowDatabase
Following is the database report for the demo_citizen database that AxHandle creates. It has been formatted for readibility.

/* Report: Database Structure */
/* Report ID: 2W5bE4RDffddeffd6KYAyyUatQmPrA */
/* DateTime: 2022080817202302 */

/* create the database */

create database demo_citizen , h:\dev\core\axlebase\axhandle\db\demo_citizen\

/* create the tables */

create table t_watcher ( citizen_id integer, unit_id integer, officer_id integer, last_update datetime, updater string(20) )

create table t_attitude_scale ( attitude integer, description string(70), last_update datetime, updater string(20) )

create table t_citizen ( citizen_id serial, name_first string(30), name_last string(30), licensed_breeder boolean, d_o_b datetime, d_o_d datetime, assigned_residence numeric, occupation_cat string(10), occupation_sub string(10), education_cat string(3), education_level string(3), intelligence numeric, last_update datetime, updater string(20) )

create table t_citizen_status ( citizen_id serial, location string(16), status string(2), watch_type string(2), flag boolean, last_update datetime, updater string(20) )

create table t_country_code ( country string(2), internet_code string(3), country_name string(50), description string(100), last_update datetime, updater string(20) )

create table t_descriptors ( citizen_id integer, dna_chart blob, face_hologram blob, hologram_date datetime, holographer integer, brain_wave_print blob, brain_wave_date datetime, brain_scanner integer, thought_scan_analysis blob, thought_scan_date datetime, thought_analyst integer )

create table t_employment_history ( citizen_id integer, permit integer, start datetime, end datetime, employer_id integer, last_update datetime, updater string(20) )

create table t_intimate ( citizen_id integer, parent_male integer, parent_female integer, sexual_1 integer, sexual_type_1 string(2), sexual_2 integer, sexual_type_2 string(2), sexual_3 integer, sexual_type_3 string(2), friend_1 integer, friend_2 integer, friend_3 integer, friend_4 integer, friend_5 integer, friend_6 integer, friend_7 integer, last_update datetime, updater string(20) )


create table t_intimate_history ( citizen_id integer, date_start datetime, date_end datetime, associate integer, type_associate string(2), last_update datetime, updater string(20) )

create table t_marriage_permit ( permit integer, citizen integer, date_assigned datetime, approved_by integer, expiration datetime, rescinded datetime, rescinded_by integer, last_review datetime, reviewed_by integer, last_update datetime, updater string(20) )

create table t_personal_permits ( citizen_id integer, birth integer, employment integer, marriage integer, night_movement integer, residence integer, travel integer, vehicle integer, voter integer, last_update datetime, updater string(20) )

create table t_residence ( citizen_id integer, date_assigned datetime, last_review datetime, residence_id integer, coordinates numeric, country string(2), political_unit string(50), sub_unit string(50), city string(50), city_zone string(50), street string(50), square_feet numeric, lock_code string(50), local_class string(10), last_update datetime, updater string(20) )

create table t_residence_history ( citizen_id integer, date_assigned datetime, date_vacated datetime, residence_id integer, coordinates numeric, country string(2), political_unit string(50), sub_unit string(50), city string(50), city_zone string(50), street string(50), square_feet numeric, lock_code string(50), local_class string(10), last_update datetime, updater string(20) )

create table t_status_code ( status string(2), status_name string(10), description string(100), last_update datetime, updater string(20) )

create table t_status_history ( citizen_id integer, start_status datetime, status string(2), watch_type string(2), flag boolean, last_update datetime, updater string(20) )

create table t_travel_history ( citizen_id integer, permit integer, start datetime, end datetime, destination string(20), purpose string(20), last_update datetime, updater string(20) )

create table t_watch_code ( watch_type string(2), watch_name string(10), description string(100), last_update datetime, updater string(20) )

/* create the indices */

/* End of report 2W5bE4RDffddeffd6KYAyyUatQmPrA */

-- . --

End of the ShowDatabase sub-section.

Click to return to document contents.

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

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

ShowDatabaseAttributes
a sub-section of the
Manager Object section



Address: jragan.com/axledoc_2.htm#70.45.45
-- . --

Syntax:
oManagerObject.ShowDatabaseAttributes

Returns the characteristics of the currently open database, as a list of name-value pairs.

Return Structure :
      The report has a header and a footer.
      The body is a sequence of attribute groups.
      Each group is prefixed by an end-of-line.
      (First prefix skips the zeroth group when arrayed.)
      Attribute elements are :
            attribute name
            space
            equal sign
            one or more formatting spaces
            value
      Values may be empty.
      Values may be null.
      Values may reference the higher domain authority.
      A line break value is represented by the string 'eol'.
      Structure enables display of elements with a split of each group.

The header and footer contain the report name and unique identification.

Since the return consists of the characteristics of the currently open database, if no database is open, the return is simply blank; it is not an error.

Toggle values in the return may be true, false, yes, no, t, f, y, or n, depending on the development stage of the system.

Storage Architecture Model :
      The SAM version number may or may not be the same as the version number that is returned by the ShowVersion command. The ShowDatabaseAttributes command returns the SAM version number currently being used, which is not the version of any software, whereas the ShowVersion command returns the version number of the currently running AxleBase.

Release Number :
      The release number may or may not be the same as the release number that is returned by the ShowRelease command. The ShowDatabaseAttributes command returns the release number of the system that created the row, whereas the ShowRelease command returns the release number of the currently running AxleBase.

The return includes the connectionId, which is the same as the ID number of the "Manager" object that created the connection.

location	The path to the database.
lock	The type of lock if any.
lockproc	The name of the process holding the lock, if any.
nullToken	The null token.
maxconnections	Maximum allowed concurrent connections.
currconnections	Current number of open connections.
tableLocks	Toggle permits table locks.
rowLocks	Toggle permits row locks.
SAMversion	The storage architecture model version currently in use.
dbmsRelease	Release number of AxleBase that created the database.

Universalization :
      This report has been formatted for understanding by people and by unattended systems.

"Security" :
      After security is activated, this requires read permission at the database level.

See also: ShowDatabaseCatalogue, ShowDomainAttributes, ShowInstanceAttributes, ShowTableAttributes, "ShowAxsys".

Return expected:   Current database characteristics.
Return on error :   "Error" message.

Example with return from the "Demo Main" database that "AxHandle" builds when he is told to run his suite of tests:
sReturn = oMgr . ShowDatabaseAttributes

Report:          Database Attributes
Report ID:       rUNOLSHRffddfgegjEDMQEiHtqWGdV
DateTime:        2022080720331036
Copyright:       Copyright 2003-2023 John E. Ragan
Licensed To:     ( unlicensed stolen system )
License Number:  ( unlicensed stolen system )
License Type:    ( unlicensed stolen system )

databaseName           = demo_citizen
databaseIdentifier     = kTNMTcJJffdfeded7nKk2GwE17KGYT
domainName             = h:\dev\axlebase\db\demodom\
domainIdentifier       = j21HNRFjfedfehgd5uDGeCJlSAxTts
location               = h:\dev\axlebase\db\
computerHost           = kong6
instanceDBA            = James
nodeLoaded             = null
nodeId                 = null
AxleBaseInstanceId     = sSiWrjKKffddfgdkIP0gyxDJNBf1qZ
dbConnectionId         = W8KJafj7ffddfgdlMBv2bvqXlEFmyi
domainConnId           = CaFZiOtPffddfgdkqoL2K7bMDZ0Psh
SAM                    = 100501
securityToggle         = off
shared to network      = no
auditTrail             = no
axsysEnabled           = yes
backfill               = 100
bufferloadersize       = null
bufferSize             = using domain setting
cacheReturns           = no
cognateDirtyDataPortal = no
cognateFailFrom        = null
cognateFailTo          = null
cognateFeedFrom        = null
cognateFeedTo          = null
cognateFlicker         = null
cognateMirrorOf        = null
cognateMirrorTo        = null
columnSeparator        = null
columnType             = using domain setting
commAuthenticate       = no
commEnvelopeEncrypt    = no
commHideErrAx          = no
commHideErrServer      = no
commHideErrSys         = no
commUseSyslink         = no
connectionLimit        = 0
DataFailoverByAll      = no
datasetSizeLimit       = 1,000,000
denyDDL                = no
denySQLupdate          = no
denyTableScans         = no
description            = demo/test database 
encryptionDepth        = 1
encryptInbound         = no
encryptOutbound        = no
exportColumnSeparator  = ^
exportRowTerminator    = -*eol*-
failOpen               = yes
hideSecurityStops      = no
locationAxsysLoc       = h:\dev\axlebase\db\dbaxs\
locationBlobs          = h:\dev\axlebase\db\dbblb\
locationIndices        = h:\dev\axlebase\db\dbndx\
locationJobs           = h:\dev\axlebase\db\dbjob\
locationLog            = h:\dev\axlebase\db\dbsys\
locationSegmentPointer = h:\dev\axlebase\db\dbspt\
locationStats          = h:\dev\axlebase\db\stats\
locationTemp           = h:\dev\axlebase\db\dbtmp\
lockTimeoutDatabase    = 3600
lockTimeoutTable       = 3600
logErrors              = no
logToggle              = no
logAutoTruncate        = null
messageSizeLimit       = 500000
nodeSleep              = 7200
nullToken              = using domain setting
maintainStats          = no
nqcrszx                = 7      not user maintainable.
nqreqrecx              = 1000   not user maintainable.
nqsmstszx              = 1000   not user maintainable.
nqsmsttrx              = 0.21   not user maintainable.
nqstszx                = 100    not user maintainable.
nqsttrx                = 0.9    not user maintainable.
password               = null
pointerLoadLimit       = using domain setting
rangeSize              = 10
returnProtocol         = using domain setting
rowTerminator          = using domain setting
segmentSize            = using domain setting
spinlock               = 0
sptLimit               = 7,000,000
statisticstoggle       = no
storageLocation        = null
storageSpace           = 0
timeoutTemp            = 1
timeZone               = 06,TER
typeOfDatabase         = oltp
vpnToggle              = off
yield processor        = using domain setting

End of Database Attributes Report
                  rUNOLSHRffddfgegjEDMQEiHtqWGdV

        

-- . --

End of the ShowDatabaseAttributes sub-section.

Click to return to document contents.

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

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

ShowDatabaseCatalogue
a sub-section of the
Manager Object section



Address: jragan.com/axledoc_2.htm#70.45.50
-- . --

Syntax:
oManagerObject.ShowDatabaseCatalogue [ attributeName , [ databaseName ] ]

Returns a list of the specified attributes for databases in the current domain.

There are times when a database name may be part of the name of another; e.g. parts and parts_auto. In that case, added programming would be required to find both. Therefore, an end-of-line is added to the last item so the host system can search for database name and eol.

AttributeName :
      Attribute name is optional.
      If no attribute is specified, all are returned.
      Following are the available attribute names :
            ID
            name
            type
            location
            description

Database Name :
      A blank database name will return the attribute for all databases.

Format :
      Attributes for each database are on a single line.
      Attributes are separated by a comma and two spaces.
      Each database line has a "db cat" header and separator.
      A line break precedes each row in the list.
      The first line break skips the zerothe element.
      The report has a header.
      An extra break separates the header from the body.
      The report has a footer.
      An extra break separates the footer from the body.
      The report numbers match in the header and footer.

If no domain is open, a trappable error message is returned.

If there are no databases in the catalogue, an empty string is returned.

Universalization :
      This report has been formatted for understanding by people and by unattended systems.

"Security" :
      After security is activated, this requires read permission at the database level.

See also: ShowDatabaseAttributes.

Return expected:   Database list.
Return on error :   "Error" message.

Example:
sReturn = oMgr.ShowDatabaseCatalogue
sReturn will contain either the catalogue or an error message.

Example:
sReturn = oMgr.ShowDatabaseCatalogue ( name, )
sReturn will contain either a database list or an error message.

Example with return from the database domain that AxHandle creates when he is told to run his suite of tests:
sReturn = oMgr.ShowDatabaseCatalogue

Report:          Database Catalogue
Report ID:       RDXgONcoffdefigj705OOLCYzbrzuS
DateTime:        2022051520583362
Copyright:       Copyright 2003-2023 John E. Ragan
Licensed To:     ( unlicensed stolen system )

   column names follow
   row hdr,  storage version,  database id,  name,  type,  location,  description 

db cat,  ,  100501,  ykakwuzrffddedgjva6jptqovjylm9,  demo_citizen,  oltp,
  h:\dev\core\axlebase\axhandle\db\demo_citizen\,  
db cat,  ,  100501,  a1njar5bffddedgfcg2s2qoae9shq7,  demo_seg,  oltp,
  h:\dev\core\axlebase\axhandle\db\demo_seg\,  
db cat,  ,  100501,  ozb8blxvffddedgmswb7kqurqwkfma,  demo_main,  oltp,
  h:\dev\core\axlebase\axhandle\db\demo_main\,  
db cat,  ,  100501,  6gt57dfaffddedgfpyjvftmnksgqed,  demo_virtual,  oltp,
  h:\dev\core\axlebase\axhandle\db\demo_virtual\,  
db cat,  ,  100501,  ygszpnvuffddedgkfagwn9zzrgarj5,  demo_audit,  oltp,
  h:\dev\core\axlebase\axhandle\db\demo_audit\,  

End of Database Catalogue Report
              RDXgONcoffdefigj705OOLCYzbrzuS


        

-- . --

End of the ShowDatabaseCatalogue sub-section.

Click to return to document contents.

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

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

ShowDomainAttributes
a sub-section of the
Manager Object section



Address: jragan.com/axledoc_2.htm#70.45.60
-- . --

Syntax:
oManagerObject.ShowDomainAttributes

Returns a string containing the identification and attributes of the currently open database domain.

Return Structure :
      This report has header and footer lines.
      The body is a sequence of attribute groups.
      Each group is prefixed by an end-of-line.
      (First prefix skips the zeroth group when arrayed.)
      Attribute elements are :
            attribute name
            space
            equal sign
            one or more formatting spaces
            value
      A line break value is represented by the string 'eol'.

The header and footer contain the report name and unique identification.

If a domain has not been opened by the current database manager object, a trappable error message is returned. This provides a way of insuring that an open command succeeded.

Universalization :
      This report has been formatted for understanding by people and by unattended systems.

"Security" :
      After security is activated, this requires read permission at the domain level.

See also: ShowDatabaseAttributes, ShowInstanceAttributes, ShowTableAttributes.

Return expected:   Character string.
Return on error :   "Error" message.

Example with return from the database domain that AxHandle creates when he is told to run his suite of tests:

sReturn = oMgr.ShowDomainAttributes

Report:          Domain Attributes
Report ID:       OKCYzbrzffddegijtSTsu8Zi5dmIha
DateTime:        2022080818335266
Copyright:       Copyright 2003-2023 John E. Ragan
Licensed To:     ( unlicensed stolen system )

domainName              = demodom
domainIdentifier        = j21HNRFjfedfehgd5uDGeCJlSAxTts
domainDatabaseLocation  = h:\dev\core\axlebase\axhandle\db\demodom\
dbms_release            = 180415
computerHost            = super6
instanceDBA             = joe
instanceStartup         = 2022080816324056
nodeLoaded              = 
nodeId                  = 
AxleBaseInstanceId      = DOTiMT3Jffddeghie7RJivwt0ffGYX
domainConnectionId      = tz3rKaVpffddeghisFovNl4mY5VT1b
currentDbName           = demo_citizen
currentDbConnId         = LMJRs2h0ffddeghjzFKOCg2rAEbAGV
SAM                     = 00501
security                = off

bufferSize              = 1000000
columnSeparator         = ¥¥
columnType              = f
connectTimeout          = 5
dbtmpLocation           = \\super6\h\dev\core\axlebase\axhandle\db\demodom\dbtmp\
logLocation             = h:\dev\core\axlebase\axhandle\db\demodom\
defaultDatabase         = demo_citizen
encrypt                 = no
lockTimeout             = 3600
nullToken               = 
password                = 
pointerLoadLimit        = 1000
queryTimeout            = 3
returnProtocol          = 
rowTerminator           = 

segmentSize             = 2000000000
spinLock                = 3
variableDelimiter       = '
wildCardCharacterMult   = *
wildCardCharacterSingle = ?
yieldProcessor          = yes

End of Domain Attributes Report OKCYzbrzffddegijtSTsu8Zi5dmIha

-- . --

End of the ShowDomainAttributes sub-section.

Click to return to document contents.

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

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

ShowErrorList
a sub-section of the
Manager Object section



Address: jragan.com/axledoc_2.htm#70.45.65
-- . --

Syntax:
oManagerObject.ShowErrorList [ errorNumber ]

Returns the entire list of standard errors. If an error number is entered, only that error is returned. There are only a few hundred in the list.

Return Structure :
      The list is designed to be read by systems as well
        as people to support management automation.
      The elements of the list are the errors.
      Each element is prefixed by an end-of-line.
      (First prefix skips the zeroth element when arrayed.)
      Each element consists of the error number and the message.

The AxleBase builder attempted to cover all of the usual errors and some general errors, but the user must be prepared for the reality of any kind of error. AxleBase will attempt to let you know if he does not recognize an error.

See also: ShowLastError.

Return expected:   Error list.
Return on error :   "Error" message.

Example:
dim oMgr as Manager
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."

-- . --

End of the ShowErrorList sub-section.

Click to return to document contents.

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

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

ShowHealth
a sub-section of the
Manager Object section



Address: jragan.com/axledoc_2.htm#70.45.70
-- . --

Syntax:
oManagerObject.ShowHealth [ [ not ] tableName [ , startSeg , LastSeg [ , sptOnly ] ]

There are times when a "DBA" wonders about the integrity of a database or table. That is especially true of "VLTs" (very large tables). This tool is provided to answer that need.

This command also provides a tool for axsys management. It can be used to take a snapshot of the database health before running a large query.

There is an at-a-glance summary at the end of the report showing total warnings found. Each table section has a similar summary line.

The operation will not check all possible problems because of the time and resources that would be required. If, for example, the operating system has inserted an illegal character two terrabytes into the table, this command will not seek it. It does, however, look for many potential problems.

TableName :
      Optional.
      The default checks all tables.
      A table name will check only that table.
      A "not" before the name will check all except that table.

Seg Spec :
      Optional.
      First seg number and last seg number.
      Can be used only with a table spec.
      Each value requires the other, but it may be zero.
      Only that range of seg files will be checked.

SptOnly :
      Optional.
      Allows limiting the check to a single operation.
      The string "sptOnly" checks the spt integrity.

Locks :
      Tables are not locked for this operation. Since the operation can take some time and can span the entire database, the process may fail if another process has an object locked. Failure of this report will do no harm; just re-run the report.

Table Scan :
      This report does not read individual rows, so it may not see a physical corruption inside a data file.
      If that problem is suspected, then also run the Purge command with the Count parameter. That command will read every row individually.
      ( A scan option is not available because scanning a hundred billion rows could take years.)

Report:
      A report is returned showing the results.
      It is formatted for machine and human readability.
      The first report section is the report header.
      Each table section begins with the table header line.
      Each table's report line begins with table name and a space.
      A problem will not interrupt the report.
      Each warning is reported on a line.
      Warning lines begin with "tableName **WARNING:".
      Concludes with a list of tests performed on all tables.
      The last line is the report footer.

Caution :
      Note that situations that would return grave error messages in other contexts will only be warnings in this report. Only an error that can interrupt this operation will return an error message. Therefore, a warning in this report may indicate a serious situation and may even indicate that data is at risk.

Some of the checks :
      Network infrastructure integrity.
      "Serial" number table existence.
      Ability to open and read all table data files.
      Integrity of SPT for all tables.
      Integrity of every SPT pointer.
      Seg file names.
      Seg file locations.
      Byte count validity of all segments.
      Row-count integrity.
      Status of all segment files.
      Integrity of all index masters.
      Index exception flags.
      Ability to open and read every index file.
      Index file names.
      Index file locations.
      Checks index file sizes against expected.

Resources :
      Remember that a VLT file count can easily be tens of thousands.
      Speed can be tested before running the report by first running it for a small range of segs.
      Tables that have trillions of rows may take some time.
      Every seg file is opened and closed to verify its health.

Data failovers :
      If a seg has failed to a failover table, then this report will warn that its file name is erroneous. It will continue to do so until the seg is recovered into the master table.

Universalization :
      This report has been formatted for understanding by people and by unattended systems.

See also: NetworkScan; ShowTable; ShowSegments; ShowTableAttributes, ShowTopology.

Return expected:   A status report.
Return on error :   "Error" message.

Example:
sReturn contained the following:
sReturn = oMgr.ShowHealth

   Report:          ShowHealth
   Report ID:       FRdBc2W2fedfehdiB
   DateTime:        2012012515450256
   Database:        demo_seg    FWpYGUwofedfedh
   Domain:          demodom    5US1azflfededhhj
   Table Count:     5
   Licensed To      ( unlicensed stolen system )
   License Number   ( unlicensed stolen system )

   T_APP_CRUD      Begin Table Report
   T_APP_CRUD Row count:      150
   T_APP_CRUD Segs:           3
   T_APP_CRUD Index count:    0
   T_APP_CRUD produced no warnings. 
   T_APP_CRUD     End Table Report

   T_CITIZEN      Begin Table Report
   T_CITIZEN Row count:      150
   T_CITIZEN Segs:           3
   T_CITIZEN Index count:    0
   T_CITIZEN produced no warnings. 
   T_CITIZEN     End Table Report

   T_CITIZEN_STATUS      Begin Table Report
   T_CITIZEN_STATUS Row count:      150
   T_CITIZEN_STATUS Segs:           3
   T_CITIZEN_STATUS Index count:    0
   T_CITIZEN_STATUS produced no warnings. 
   T_CITIZEN_STATUS     End Table Report

   T_CONFIG      Begin Table Report
   T_CONFIG Row count:      150
   T_CONFIG Segs:           3
   T_CONFIG Index count:    0
   T_CONFIG produced no warnings. 
   T_CONFIG     End Table Report

   T_LOG      Begin Table Report
   T_LOG Row count:      150
   T_LOG Segments:           3
   T_LOG Index count:    0
   T_LOG produced no warnings. 
   T_LOG     End Table Report

   The report contains no warnings.

   End of ShowHealth Report FRdBc2W2fedfehdiB

Not shown here is a checklist in the report footer.

-- . --

End of the ShowHealth sub-section.

Click to return to document contents.

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

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

ShowHostAttributes
a sub-section of the
Manager Object section



Address: jragan.com/axledoc_2.htm#70.45.75
-- . --

Host attributes are stored with the database attributes. See the ShowDatabaseAttributes command. To obtain its configuration, the host will run the ShowDatabaseAttributes report and extract the needed values.

-- . --

End of the ShowHostAttributes sub-section.

Click to return to document contents.

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

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

ShowIndices
a sub-section of the
Manager Object section



Address: jragan.com/axledoc_2.htm#70.45.80
-- . --

Syntax:
oManagerObject.ShowIndices [ tableName [, indexName] ]

Returns an index report for the database or for the specified table.

Table Name and Index Name :
      The table name and index name are optional. If the index name is specified, then the table name must be specified.

Return Structure :
      This report has header and footer lines.
      The header line names the elements listed below.
      The body consists of index descriptions.
      Each index description consists of elements.
      Elements are separated by a comma and a space.
      The elements are :
            the literal "** index description"
            table name
            index name
            key
            unique
            active
            index identity
            index width
            column names separated by single space
The lack of a description line shows that there are no indices to report.

The header and footer contain the report name and unique identification.

Universalization :
      This report has been formatted for understanding by people and by unattended systems.

Return expected:   An index list.
Return on error :   "Error" message.

Example:
sReturn = oMgr.ShowIndices ( "T_LOG" )
sReturn will contain either the index data or an error message.

-- . --

End of the ShowIndices sub-section.

Click to return to document contents.

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

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

ShowInstanceAttributes
a sub-section of the
Manager Object section



Address: jragan.com/axledoc_2.htm#70.45.85
-- . --

Syntax:
oManagerObject.ShowInstanceAttributes

This command tells the "Manager" object to describe his current "Instance".

The return is a descriptive string of elements that consist of the element description, an equal sign, the element data, and an EOL terminator.

Included are :
      Information about the system defaults that may or may not be currently in use by a domain or database and that may or may not be applied to a domain or database when it is subsequently opened.
      Current values of AxleBase internal settings.
      Information about the computer on which the instance is loaded.
      The unique identifier for that instance.
      Other miscellaneous information from the instance level.

The instance identifier is valid only as long as that instance is alive. (Pursuant to the command of Him for whom I work, identifiers created by my systems cannot be used to identify hardware, platform, owner, or anything else other than that which is openly specified.)

Universalization :
      This report has been formatted for understanding by people and by unattended systems.

"Security" :
      After security is activated, if a database is open, then this requires read permission at the database level. No permission is needed if no database is open.

See also: ShowInstanceID, ShowDomainAttributes, ShowDatabaseAttributes, ShowTableAttributes.

Return expected:   Descriptive information.
Return on error :   "Error" message.

Example:
sReturn = oMgr.ShowInstanceAttributes
sReturn will contain either the instance data or an error message.

Example:
sReturn contained the following:
sReturn = oMgr.ShowInstanceAttributes

Report:          Instance Attributes
Report ID:       Z7Wi3c1hffddeiihnH73uEa6Ybmrky
DateTime:        2022080818535548
Copyright:       Copyright 2003-2023 John E. Ragan
Licensed To:     ( unlicensed stolen system )

name               = AxleBase
legal              = Copyright 2003-2023 John E. Ragan
version            = 2.00
release            = 220514
sam                = 100501
sysLinkRelease     = 20512
instanceFile       = axlebase.dll
instancePath       = h:\dev\core\axlebase\dev\
instanceMode       = production
instanceColSep     = »¤¤«
instanceDblDelEsc  = »¿¿«
instanceDelEsc     = »¯¯«
instanceDeleted    = ¤
instanceRowTerm    = (eol)
instanceRowTermEsc = ÿÿ

instanceLogin      = joe
computerName       = super6
instanceId         = DOTiMT3Jffddeghie7RJivwt0ffGYX
instanceStartTime  = 2022080816324056
testMode           = no
currentDomain      = demodom
currentDb          = demo_citizen

defaultDbBuffer    = 1000000
defaultDbSegment   = 2000000000
defaultDbColSep    = ¥¥
defaultDbRecTerm   = (eol)
defaultDbNull      = (ASCII 127)
defaultDbWildMult  = *
defaultDbWildSing  = ?
defaultDbColType   = f
defaultDbDelimEsc  = (there is no default)
defaultDbPntrLdLmt = 1000
userLocation       = 
userId             = 

End of Instance Attributes Report Z7Wi3c1hffddeiihnH73uEa6Ybmrky

-- . --

End of the ShowInstanceAttributes sub-section.

Click to return to document contents.

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

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

ShowInstanceID
a sub-section of the
Manager Object section



Address: jragan.com/axledoc_2.htm#70.45.90
-- . --

Syntax:
oManagerObject.ShowInstanceID

This command tells the "Manager" object to return his "Instance" identification number.

When AxleBase is opened, he creates a unique identifier for himself. Thus, each running instance of AxleBase has an identifier. The identifier is case sensitive.

Each instance ID remains valid for as long as the instance runs and may be used to identify extant instances. When an instance terminates, the ID disappears.

( Pursuant to the command of Him for whom I work, identifiers created by my systems cannot be used to identify hardware, platform, organization, individual, or another system. These numbers are what they claim to be and are no more. Also, when the instance terminates, the identifier disappears.)

See also: ShowInstanceAttributes

Return expected:   The identifier of the current instance.
Return on error :   "Error" message.

Example:
sReturn = oMgr.ShowInstanceID
sReturn will contain either the instance ID or an error message.

-- . --

End of the ShowInstanceID sub-section.

Click to return to document contents.

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

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

ShowJobs
a sub-section of the
Manager Object section



Address: jragan.com/axledoc_2.htm#70.45.93
-- . --

Syntax:
oManagerObject.ShowJobs

Returns a report containing the jobs that are on file from the CreateJob command.

Notice that it is plural.

See also: CreateJob, DropJob, RunJob .

Return expected:   The jobs report.
Return on error :   "Error" message.

Example:
sReturn = oMgr.ShowJobs

-- . --

End of the ShowJobs sub-section.

Click to return to document contents.

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

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

ShowJobState
a sub-section of the
Manager Object section



Address: jragan.com/axledoc_2.htm#70.45.95
-- . --

Syntax:
oManagerObject.ShowJobState

Returns the status of the currently running job or of the last job. The YieldProcessor configuration must be on for this command to work properly. (This command was created primarily for development. Since it adds to run time, it may later be dropped if its usefulness diminishes.)

Not all jobs maintain the internal state table. Most jobs that sometimes have a long run time, such as an index creation or a query, will maintain their job state.

Return Structure :
      The return is a string of elements.
      Each value is prefixed by a vertical bar.
      (First one is prefixed to skip the zerothe when arrayed.)
      An element is a vertical bar, its name, an equal, and value.
      The elements are:
            job name
            start time
            stop time
            duration
            state number
            state
            step number
            step name
            source number (virtual tables)
            segment number
            row segment
            row total
            changes
            cycles
            table name

Duration :
      The run time is the duration in seconds of the currently running job or, if none is running, of the last executed job.
      If a more precise time is needed, the start and stop times are returned for calculations. They are datetime values specified to hundredths of a second.

Row Numbers :
      The row segment is the approximate number of the last row processed in the current segment.
      Row total is the rows in all segments processed.

Cycles :
      For an automatic process, this gives the cycles completed during and after the process is stopped.

An additional use is the location of a value. If a query is a select with a where, then this command will return the last segment number in which the specified value was found.

Job States :
        running
        complete
        aborted
        stopped
        An empty string for jobs that do not report a state.

Universalization :
      This report has been formatted for understanding by people and by unattended systems.

See also: "AbortJob"

Return expected:   The job state string.
Return on error :   "Error" message.

Example:
sReturn = oMgr.ShowJobState
sReturn will contain either the job state or an error message.
|name=connectionstring|start=2015080716415139 |stop=2015080716415194|duration=0.55|state_number=1 |state=complete|step_number=1|step_name=|source=0 |segment=0|row_segment=0|row_total=0|changes=0 |cycles=0|table=

-- . --

End of the ShowJobState sub-section.

Click to return to document contents.

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

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

ShowLastError
a sub-section of the
Manager Object section



Address: jragan.com/axledoc_2.htm#70.48.05
-- . --

Syntax:
oManagerObject.ShowLastError [ elementName ]

Returns the row of the last error that AxleBase identified. An error remains available to the host system until the next error or until the host system clears it.
      To capture errors of all instances that are running against the database, logging must be on.

Element Name :
      Optional. :
      Specification of a name will return only that element.
      No name will return the entire error string.
      Valid names are :
            header
              id
              type
              source
              time
              message

To insure that the return is not mistaken as an error return by the host, the return is prefixed by 'last error at (time)=', where (time) is the standard datetime of the error.

Universalization :
      This report has been formatted for understanding by people and by unattended systems.

See also: AxleBase Error Protocol and ClearLastError.

Return expected:   The last error
Return on error :   "Error" message.

Example:
sReturn = oMgr.ShowLastError
sReturn will contain either the desired message or a current error message.

-- . --

End of the ShowLastError sub-section.

Click to return to document contents.

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

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

ShowLicense
a sub-section of the
Manager Object section



Address: jragan.com/axledoc_2.htm#70.48.10
-- . --

Syntax:
oManagerObject.ShowLicense

Returns the software license agreement to which the creator and user agreed.

The return is approximately four thousand bytes of formatted text containing ASCII characters 13 and 10 for line feeds and carriage returns.

Any attempt to mask, bypass, alter, alias, camouflage, or qualify either this command or its return legally revokes the right of the individual and/or organization to use AxleBase and its supporting software and may precipitate legal consequences.

See also the ShowCopyright command.

Return expected:   The software license.
Return on error :   "Error" message.

Example:
sReturn = oMgr.ShowLicense
sReturn will contain the AxleBase software license that you accepted.

-- . --

End of the ShowLicense sub-section.

Click to return to document contents.

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

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

ShowLicenseGrant
a sub-section of the
Manager Object section



Address: jragan.com/axledoc_2.htm#70.48.15
-- . --

Syntax:
oManagerObject.ShowLicenseGrant

Returns the license information from the current "Instance".

Return expected:   The license information.
Return on error :   "Error" message.

Example:
sReturn = oMgr.ShowLicenseGrant

-- . --

End of the ShowLicenseGrant sub-section.

Click to return to document contents.

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

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

ShowLocks
a sub-section of the
Manager Object section



Address: jragan.com/axledoc_2.htm#70.48.20

last update 202302**
-- . --

Syntax:
oManagerObject.ShowLocks

Returns a list of the currently open locks to which the requestor is authorized access.

Lack of security clearance will not return an error. Lack of an open domain or database will not return an error.

"Security" :
      After security is activated, this requires read permission at the domain and database levels.

Inclusion :
      Descretionary and autonomic locks are included.
      Because of the autonomic locks, the list offers an immediate list of systems and individuals currently working in the database.

Return Structure :
      Report has a header and footer.
      Each lock is prefixed by an end-of-line.
      (Including first one to bypass zerothe when arrayed.)
      Each lock consists of elements.
      Elements are not named, but there is a header line.
      Elements are prefixed by commas.
      Elements are :
            lock ID
            time locked
            lock type
            object type
            object name
            locker ID
            login ID
            computer name
            "Instance" ID

The header and footer contain the report name and unique identification.

Universalization :
      This report has been formatted for understanding by people and by unattended systems.

See also the "LockObject", ShowTableAttributes, ShowDatabaseAttributes, and ShowDomainAttributes commands.

Return expected:   The lock list.
Return on error :   "Error" message.

Example:
sReturn = oMgr.ShowLocks
sReturn will contain the list of current locks.
In this case, the report finds only two locks open.

Return Example:
Report: Lock
Report ID: 5cGPkwhKffdedfdfDDBI4HQCGjgMZL
DateTime: 2022081100240828

, lock id , time locked , lock type , object type , object name , locker , login , computer , instance

, CGMsNUokffdedeihA9ys9Qgt6XQ03b , 2022081100145144 , i , database , , joe , superjoe , super6 , ERtY8O3XffdedeigcT701y6kakLsuz

, a0wMlEMHffdedeihXrFHVdSnSDr452 , 2022081100145139 , i , domain , , joe , superjoe , super6 , ERtY8O3XffdedeigcT701y6kakLsuz

End of report 5cGPkwhKffdedfdfDDBI4HQCGjgMZL

-- . --

End of the ShowLocks sub-section.

Click to return to document contents.

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

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

ShowLog
a sub-section of the
Manager Object section



Address: jragan.com/axledoc_2.htm#70.48.25
-- . --

When logging is turned on, a read-only virtual log table is created in the database. It can be queried and managed like any other virtual table. It is virtual because the log data is stored elsewhere. When logging is turned off, it is dropped. The name of the table is T_SYS_ZSMX_DB_LOG.

Since it is a virtual table and is not indexed, retrieval is slower than well-maintained data tables.

Universalization :
      It is a table query without additional formatting.
      Errors are inserted in toto.
      Errors occupy multiple rows due to variable lengths.

-- . --

End of the ShowLog sub-section.

Click to return to document contents.

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

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

ShowPermissions
a sub-section of the
Manager Object section



Address: jragan.com/axledoc_2.htm#70.48.30
-- . --

Syntax:
oManagerObject.ShowPermissions [ level ] [ , detail [ , name ] ]

Returns the permissions if security is turned on.

Level :
      Optional.
      Limits the return to a level.
      Defaults to database.
      Permitted values :
            domain
            database

Detail :
      Optional.
      A specification within a level.
      Permitted values :
            table
            job
            entity
      In this context, entity is a person or process and not table.

Return Structure :
      Report has a header and footer.
      Body consists of permission rows.
      Each row is prefixed by an end-of-line.
      Each row consists of elements.
      Each element consists of :
            element type name
            equal sign
            value
            comma
            space
      Element types are :
            object type
            object name
            entity
            password
            owner
            create
            read
            update
            delete
            execute

Universalization :
      This report has been formatted for understanding by people and by unattended systems.

"Security" :
      After security is activated, this requires read permission at the database or domain level.

See also: Grant, Revoke and the AxleBase Lock Granularity) in the Embedding And Running AxleBase chapter.

Return expected:   Permission list.
Return on error :   "Error" message.

Example:
sReturn = oMgr.ShowPermissions database demo
sReturn will contain the permission list or an error message.

-- . --

End of the ShowPermissions sub-section.

Click to return to document contents.

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

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

ShowRelease
a sub-section of the
Manager Object section



Address: jragan.com/axledoc_2.htm#70.48.35
-- . --

Syntax:
oManagerObject.ShowRelease

Returns a string containing the five digit release number of the currently running AxleBase system.

This may or may not be the same as the release number that is returned by the ShowDatabaseAttributes command. The release number that is shown as a database attribute is the SAM (storage access model) release which is the physical protocol according to which that database was constructed. The SAM release number is usually the release number of the system that created the database and may or may not be the same as the current system release.

Universalization :
      This report has been formatted for understanding by people and by unattended systems.

See also: ShowVersion.

Return expected:   The release number.
Return on error :   "Error" message.

Example:
sReturn = oMgr.ShowRelease
sReturn will contain either the release number or an error message.

-- . --

End of the ShowRelease sub-section.

Click to return to document contents.

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

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

ShowReservedWordList
a sub-section of the
Manager Object section



Address: jragan.com/axledoc_2.htm#70.48.40
-- . --

Syntax:
oManagerObject.ShowReservedWordList

Returns a list of the words that are reserved by AxleBase.

There are words that, if used as an object name or as an object attribute, would conflict with SQL commands, AxleBase controls, or other system controls. This list is used by AxleBase to check object names for those words.

Because AxleBase also cross checks configurable attributes, this is a dynamic list. For example, if the null character string is changed by the "DBA", AxleBase will change it in this list so other attributes can be checked against it.

The string may contain extended character strings. Character strings that are operating system or AxleBase control codes may or may not be returned.

Each element of the list, including the first one, is prefixed by an end-of-line. The first one is prefixed to skip the zerothe when arrayed. If the list contains an eol, it is represented by the literal string "eol".

Universalization :
      This report has been formatted for understanding by people and by unattended systems.

There is a list in the "Reserved Words" section that might give some guidance, but it is ten or twenty years old.

Return expected:   String of reserved words.
Return on error :   "Error" message.

Example:
sReturn = oMgr.ShowReservedWordList
sReturn will contain either the reserved word list or an error message.

-- . --

End of the ShowReservedWordList sub-section.

Click to return to document contents.

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

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

ShowReturnProtocol
a sub-section of the
Manager Object section



Address: jragan.com/axledoc_2.htm#70.48.45
-- . --

Syntax:
oManagerObject.ShowReturnProtocol

Returns the name of the return protocol that is set for the currently open database.

Universalization :
      This report has been formatted for understanding by people and by unattended systems.

See also:
      The "Return Protocol" configurable attribute for a list of available AxleBase return protocols with descriptions
      Or the "Data Retrieval Tools" compendium for more information.

Return protocol settings that AxleBase recognizes are :
      html
      htmlpage
      soap
      standard
      text
      textSeparated
      xml

Return expected:   Return protocl.
Return on error :   "Error" message.

Example:
sReturn = oMgr.ShowReturnProtocol
sReturn will contain either the return protocol or an error message.

-- . --

End of the ShowReturnProtocol sub-section.

Click to return to document contents.

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

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

ShowSegments
a sub-section of the
Manager Object section



Address: jragan.com/axledoc_2.htm#70.48.50
-- . --
^

This advanced technology has been temporarily

moved off line during the documentation editing.

This command returns a report of division with specifications for each division.

-- . --

End of the ShowSegments sub-section.

Click to return to document contents.

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

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

ShowTable
a sub-section of the
Manager Object section



Address: jragan.com/axledoc_2.htm#70.48.55
-- . --

Syntax:
oManagerObject.ShowTable tableName

Returns a table's structure in a DML statement format.

If the specified table is not found in the database, a trappable error is returned.

"Security" :
      After security is activated, this requires read permission at the database level.

Universalization :
      This report delivers industry-standard DDL that may or may not be read by people and and unattended systems.

See also: ShowTables, ShowTableAttributes, ShowColumns .

Return expected:   The table DML.
Return on error :   "Error" message.

Example:
sReturn = oMgr.ShowTable ( "T_LOG" )
sReturn will contain either the SQL statement or an error message.

-- . --

End of the ShowTable sub-section.

Click to return to document contents.

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

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

ShowTableAttributes
a sub-section of the
Manager Object section



Address: jragan.com/axledoc_2.htm#70.48.60

last update 20230310
-- . --

Syntax:
oManagerObject.ShowTableAttributes tableName

Returns a string containing the identification and attributes of the specified table.

Return Structure :
      The report has a header and a footer.
      The body is a sequence of attribute groups.
      Each group is prefixed by an end-of-line.
      (First prefix skips the zeroth group when arrayed.)
      Attribute elements are :
            attribute name
            space
            equal sign
            space
            value
      Values may be empty.
      Values may be null.
      Values may reference a higher authority.
      A line break value is represented by the string 'eol'.
      Structure is designed to yield elements when a group is split programatically.

The header and footer contain the report name and unique identification.

Universalization :
      This report has been formatted for understanding by people and by unattended systems.

"Security" :
      After security is activated, this requires read permission at the database level.

See also: ShowTable, ShowTableAttributes, ShowColumns .

Return expected:   Character string.
Return on error :   "Error" message.

An example with a return from the AxHandle's demo:
sReturn = oMgr.ShowTableAttributes T_LOG_AUDIT

Report: Table Attributes
Report ID: K32kW3SeffddeeiizydjD30rA2VYin
DateTime: 2023030819155856
Copyright: Copyright 2003-2022 John E. Ragan
Licensed To: ( unlicensed stolen system )

table name = T_VIRTUAL_LOG_CAT
table identifier = XxK0DS9rffdeeffdrNmJgIkL7yHDeM
SAM = 100501
dbms name = demo_virtual
dbms identifier = JaENiufIffdeeffmBBG2s29oAE9hQK
dbms release = 220514
table type = virtual, concatenated tables

active = yes
columnSeparator = (using db or domain setting)
columnType = f
dataFailover = no
description = This table is a virtualized concatenation of other tables.
indexed = no
keyed = no
lock = r
name = T_VIRTUAL_LOG_CAT
nameAlias = null
nullToken = null
password = null
rowTerminator = (using db or domain setting)
shared = xyes
sourceCount = 5
sourceType = c
sourceConnString = null
sourceDatabases = [database(s)],demo_main, demo_main,demo_virtual, demo_main, demo_seg
sourceTables = [source name(s)],t_log, t_log_dup,t_log,t_log,t_log
sourceDomains = [domain(s)],h:\dev\db\demodom\, h:\dev\db\demodom\, h:\dev\db\demodom\, h:\dev\db\demodom\, h:\dev\db\demodom\
sourceTextFiles = null
sourceFileLocs = null
sourceMakeString = null
sourceSptLocs = proprietary internet denial
dataFailover = null

End of Table Attributes Report
K32kW3SeffddeeiizydjD30rA2VYin

-- . --

End of the ShowTableAttributes sub-section.

Click to return to document contents.

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

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

ShowTables
a sub-section of the
Manager Object section



Address: jragan.com/axledoc_2.htm#70.48.70
-- . --

Syntax:
oManagerObject.ShowTables ( [ boolean ] )

Returns a list of the tables in the database.

A lack of tables in a database is not considered an error because there are valid reasons for a database not having any tables. Therefore, an empty string is returned when no tables are found.

Return Structure :
      The report has a header and a footer.
      The header and footer contain the report identifier.
      The body is a sequence of rows.
      Rows are :
            the literal "** table"
            a comma, and a space,
            unique table identifier,
            a comma, and a space
            table name
            eol characters 13 and 10.

The header and footer contain the report name and unique report identification.

"Boolean" :
      Optional parameter.
      Provided for autonomic system activity.
      A positive boolean will return a list of names only.
      Each name will be preceeded by chr(13) and chr(10).

Universalization :
      This report has been formatted for understanding by people and by unattended systems.

"Security" :
      After security is activated, this requires read permission at the database level.

See also: ShowTable, ShowTableAttributes.

Return expected:   The table list.
Return on error :   "Error" message.

Example:
sReturn = oMgr.ShowTables
sReturn will contain either a list of all tables or an error message.

Example will return only a list of names:
sReturn = oMgr.ShowTables ( yes )

Report: Tables
Report ID: KmeEHw5PffdedifgM0ttrydmxEkj7s
DateTime: 2022081100592331
Copyright: Copyright 2003-2023 John E. Ragan
Licensed To: ( unlicensed stolen system )
Database: demo_citizen pSmi7JOdffdfeefi8HVOyE2NE6dqro

line label, Table Identification , Table Name

** table , cg5n0ms7ffdfeefmjiWW3RzKxPj1jg, T_WATCHER
** table , FDz9C75MffdfeefjB6Z9ebH8UGNDD1, T_ATTITUDE_SCALE
** table , OxIvNhyhffdfeefddvrH0HCSlmACQs, T_CITIZEN
** table , RSPXB8BnffdfeefkJ5LQUImLxaKhZM, T_CITIZEN_STATUS
** table , T0PbwuagffdfeefkA0xozSVfk5TVdr, T_COUNTRY_CODE
** table , g9TLkxxvffdfeefk2hhIZrw0oHSmpC, T_DESCRIPTORS
** table , VvtR7PBgffdfeefkBRId5UxmgxFzhv, T_EMPLOYMENT_HISTORY
** table , LTP3AEgqffdfeefk0omC7qfO59V4OJ, T_INTIMATE
** table , zUew5hx5ffdfeefdzYny0X8jsCOngh, T_INTIMATE_HISTORY
** table , nIHQUImLffdfeeflxuJhZMapWVDDkx, T_MARRIAGE_PERMIT
** table , 0wn9ZCRUffdfeeflf45TVdjJDMiufH, T_PERSONAL_PERMITS
** table , Gdh5tn0mffdfeeflt8jiWCkRgLeQW1, T_RESIDENCE
** table , 3Hgiw2sDffdfeefla1teHUUSZEEq87, T_RESIDENCE_HISTORY
** table , 8V4O1D2iffdfeeflEfdArv1W2B9SOp, T_STATUS_CODE
** table , zXnB0X8iffdfeeflCOmz0y5VkKty2q, T_STATUS_HISTORY
** table , KiGNbDW1ffdfeefm1XewTqSuDjEULf, T_TRAVEL_HISTORY
** table , Sk6ACQskffdfeefmKM1VbS5yzx4is3, T_WATCH_CODE

End of report KmeEHw5PffdedifgM0ttrydmxEkj7s

-- . --

End of the ShowTables sub-section.

Click to return to document contents.

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

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

ShowTopology
a sub-section of the
Manager Object section



Address: jragan.com/axledoc_2.htm#70.48.75
-- . --
^

This advanced technology has been temporarily

moved off line during the documentation editing.

This command will return a general description of the table's physical topology.

-- . --

End of the ShowTopology sub-section.

Click to return to document contents.

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

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

ShowVersion
a sub-section of the
Manager Object section



Address: jragan.com/axledoc_2.htm#70.48.80
-- . --

Syntax:
oManagerObject.ShowVersion

Returns a string containing the AxleBase version number.

This may or may not be the same as the version number that is returned by the ShowDatabaseAttributes command.

Universalization :
      This report has been formatted for understanding by people and by unattended systems.

See also: ShowRelease.

Return expected:   The current version.
Return on error :   "Error" message.

Example:
sReturn = oMgr.ShowVersion
sReturn will contain either the version number or an error message.

-- . --

End of the ShowVersion sub-section.

Click to return to document contents.

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

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

ShutDown
a sub-section of the
Manager Object section



Address: jragan.com/axledoc_2.htm#70.48.85
-- . --

Syntax:
oManagerObject.ShutDown

Usually, creating and destroying a "Manager" is all that is needed. The creation of a Manager object initializes AxleBase and destroying the Manager object stops all operations before the Manager goes down. However, the experienced software engineer learns that such operations cannot always be relied upon in complex environments, so this command is provided.

If the host attempts to destroy the object summarily during complex operations, those operations may continue running which will hang the object in RAM causing what is known as a memory leak. This command can be issued before destroying the object to test for a good return. If there is no return, the object is busy. If an error is returned, action should be considered before destroying the object.

Data Objects :
      If the Manager object was told to instantiate "Vector"s with the DataObjectCreate command, then this command will destroy them. :
      It cannot destroy objects that the host directly creates.

Actions :
      It runs DataObjectDestroy.
      Drops database and domain locks.
      Checks system tables.
      Resets the job state.
      Closes database and domain.
      Terminates node operations.
      Shuts down internal processes.

Return expected:   Nothing.
Return on error :   "Error" message.

Example. This is a summary of how the "AxHandle" app does it.:
If Not oMgr Is Nothing Then
    sReturn = oMgr.ShutDown
    If sReturn <> "" Then
        run the AxHandle error handlers
    End If
    If Not oVector Is Nothing Then
        set oVector = nothing
        If Not oVector Is Nothing Then
            run the AxHandle error handlers
        End If
    End If
    Set oMgr = Nothing
    If Not oMgr Is Nothing Then
        run the AxHandle error handlers
    End If
End If
Example uses sReturn to catch error returns.

-- . --

End of the ShutDown sub-section.

Click to return to document contents.

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

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

TestMode
a sub-section of the
Manager Object section



Address: jragan.com/axledoc_2.htm#70.48.87
-- . --

Syntax:
oManagerObject.TestMode booleanValue

The test mode is a state of the AxleBase "Instance". This command can set the current AxleBase instance into a test mode, or take it out of test mode.

Actions are not committed in the test mode. Each command is run up until an action would take place and is then exited.

A test mode remains in effect until the operator changes it or until the AxleBase instance is destroyed. It is not persisted.

The value can be anything that AxleBase would recognize as boolean. Some examples are yes, no, true, false, 1, 0, y, n, t, f.

The current state of the test mode can be seen by running ShowInstanceAttributes.

The test mode will check :
      Command name.
      Parameters.
      Syntax.
      Security clearance.

Scope :
      The test mode applies to all AxleBase commands including the "Vector"'s SQL operations.
      Exceptions: The following do not run or recognize tests.
          Reports.
          Open and close system.
          Open and close database.
          Open and close system domain.

Action :
      If no error is encountered, nothing is returned. If an error is encountered, the standard error is returned. Insure that the "DBA" has not turned off or suppressed error returns, which can defeat even security errors.

The TestMode and the test option in the "Appendix" clause are not exclusive. If either is true, then the command will only be tested.

See also: "Appendix" and "Test".

Return expected:   None.
Return on error :   "Error" message.

Example:
sReturn = oMgr.TestMode ( "yes" )
Example uses sReturn to catch error returns.

-- . --

End of the TestMode sub-section.

Click to return to document contents.

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

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

TruncateLog
a sub-section of the
Manager Object section



Address: jragan.com/axledoc_2.htm#70.48.90
-- . --

Syntax:
oManagerObject.TruncateLog [ rowCount ]

Truncates the log of the currently open database. It deletes and Purges. The log is locked during this operation, so it may interfere with personnel or unattended processes that use the log.

Row Count :
      Optional.
      A valid number will drop that many rows.
      Omit or enter zero to clear entire log.
      The keyword "HALF" will drop the older half of the log.

See also: ShowLog, Log Toggle, Log Auto Trucate.

Return expected:   None.
Return on error :   "Error" message.

Example:
sReturn = oMgr.TruncateLog
Example uses sReturn to catch error returns.

-- . --

End of the TruncateLog sub-section.

Click to return to document contents.

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

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

WriteMap
a sub-section of the
Manager Object section



Address: jragan.com/axledoc_2.htm#70.48.95
-- . --
^

This advanced technology has been temporarily

moved off line during the documentation editing.

The write map allows the DBA to control the location and distribution of the database. It tells AxleBase where to place a table's files, and can entirely bypass the local disk. See also the "Write Map" discussion in the Advanced Topics chapter.

-- . --

End of the WriteMap sub-section.

Click to return to document contents.

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

__________________________
<><><><><><><><><><><><><>

Data Vector Object Interface
a section of the
API Lexicon And Syntactical Reference chapter



Address: jragan.com/axledoc_2.htm#70.50.00
-- . --

-- . --

End of this Data Vector section header.

Click to return to document contents.

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

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

General
a sub-section of the
Vector Object section



Address: jragan.com/axledoc_2.htm_2#70.50.03
-- . --

( This sub-section may be of interest only to software engineers.)

The data Vector object is a vector for data. It is a vector in both the mathematical and biological sense. Its purpose is to work with data. It can insert new data, change data, and retrieve and hold a set of data while the user-host reads it or works with it.

Example:
object.ExecuteSql "select * from statistic"
for iCount = 1 to object.TupleCount
      read data from the tuple number iCount
next iCount

Where a return is expected, the return should be checked for an error message.

Delimiters :
      Do not let the big name brands confuse you ; the industry's standard variable delimiter is the apostrophe. It is not a single quote.
      Where a value contains a delimiter, see the "Delimiter Escape" sub-section.

Set Control :
      The world-wide programming community identifies the first element in a set as the zeroth element. However, after decades of wrestling with that illogical syntax, I am just plain tired of my inability to be illogical.

Therefore, AxleBase identifies the first element of a dataset as the first element. The number of elements in a set is the number of elements in the set and not the number of elements minus one.

Therefore, when you want the first row of a dataset from AxleBase, please specify row number one (1). When you want the fifth column, please specify column five (5). If AxleBase retrieves eleven (11) rows of data, he will tell you that he retrieved eleven (11) rows and not ten (10).

Vector Initilization :
      Some database managers must be initialized for each usage. The AxleBase data Vector object initializes itself when it receives a command that seems to require it. So although it is always a good practice, it is not necessary to re-initialize the object for every query.

Parentheses :
      At this point in his development, AxleBase is critical of unnecessary parentheses. When a superflous parenthetical enclosure is encounterd in a "where" clause, he will pause to return an error message.

-- . --

End of the Data Vector introduction sub-section.

Click to return to document contents.

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

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

Table Name Precedence
a sub-section of the
Vector Object section



Address: jragan.com/axledoc_2.htm#70.50.04
-- . --

AxleBase provides multiple handles for each table. They are not necessary and are provided only for those who need them. All of them can be in simultaneous use for any or all tables.

A table's potential names :
      Standard table name.
      SQL alias
      virtual source names
      table attribute alias
      axsys alias names

Precedence can best be understood by understanding the use of each.

Each table's attributes include an alias. The table is aliased simply by entering a name in that attribute. That name may never again be seen. However if a SQL statement contains a table name that cannot be found in the database, AxleBase automatically checks all of the database's attribute aliases for that name.

The axsys alias is even more complex. It knows that it is an alias for a table in the database and that table may be identified by a name or an attribute alias. (Each table's attributes include an alias.) It will first look for a real table name and if a real name is not found, it will then look for an attribute alias.

If the SQL uses a table alias, all of the above operations are performed first. Then, after the table is found, regardless of whether the name is real or an alias, the SQL alias will be applied in the SQL operation.

Precedence :
      Since various aliases may become operational simultaneously for a table, AxleBase assigns the following precedence :
          virtual source table name
          table name
          table alias
          axsys aliases
          SQL alias

-- . --

End of the Table Name Precedence sub-section.

Click to return to document contents.

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

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

ColumnContents
a sub-section of the
Vector Object section



Address: jragan.com/axledoc_2.htm#70.50.05
-- . --

Syntax:
sReturn = oDataObject. ColumnContents( ColumnName | columnNumber [ , tupleNumber ] )

Returns the contents of the specified tuple column.

Column Specification :
      The column may be specified by its name or by its position in the tuple. ( Remember that element number one is one and is not element number zero.)

TupleNumber :
      Optional. If used, it directs the return of data from that tuple. If the tuple number is not passed, and the current cursor pointer is greater than zero (0), then the current tuple is red. If it is not passed and the pointer is zero (0), then the first tuple is red.

An error message is returned if the dataset is empty.

Return expected:   A column's contents.
Return on error :   "Error" message.

Example:
sReturn = oData. ColumnContents ( log_msg )
sReturn = oData.ColumnContents ( 4 , 563 )
sReturn will contain either the data from the column or an error message.

-- . --

End of the ColumnContents sub-section.

Click to return to document contents.

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

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

ColumnCount
a sub-section of the
Vector Object section



Address: jragan.com/axledoc_2.htm#70.50.07
-- . --

Syntax:
sReturn = oDataObject.ColumnCount

Returns the number of columns that were retrieved in the dataset.

If no data was found, there are no columns, so this is zero.

Operations with a remote server may be faster if the "ShowDatasetAttributes" command is used to retrieve all of the attributes in a single return.

Return expected:   Column count.
Return on error :   Minus one (-1).

Example:
sReturn = oData.ColumnCount
sReturn will contain either the count or an error message.

-- . --

End of the ColumnCount sub-section.

Click to return to document contents.

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

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

ColumnName
a sub-section of the
Vector Object section



Address: jragan.com/axledoc_2.htm#70.50.10
-- . --

Syntax:
sReturn = oDataObject. ColumnName( columnNumber )

Returns the name of the specified column.

Returns an error message if the column is undefined. It is defined after the host app executes a SQL query.

Operations with a remote server may be faster if the "ShowDatasetAttributes" command is used to retrieve all of the attributes in a single return.

Return expected:   A column name
Return on error :   "Error" message.

Example:
sReturn = oData.ColumnName ( 4 )
sReturn will contain either the column name or an error message.

-- . --

End of the ColumnName sub-section.

Click to return to document contents.

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

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

ColumnStart
a sub-section of the
Vector Object section



Address: jragan.com/axledoc_2.htm#70.50.13
-- . --

Syntax:
sReturn = oDataObject.ColumnStart( " name " | position_number )

Returns the starting position of the specified column. Either a name or position number may be used to specify the column.

Returns zero (0) if the column is undefined. It is defined after the host app executes a SQL query.

Operations with a remote server may be faster if the "ShowDatasetAttributes" command is used to retrieve all of the attributes in a single return.

Return expected:   Column start position.
Return on error :   Minus one (-1).

Example:
sReturn = oData.ColumnStart ( "log_msg" )
sReturn will contain either the "Integer" value or an error flag.

See also: Column Name, Column Count, Column Contents, Column Start, Column Type, Column Width

-- . --

End of the ColumnStart sub-section.

Click to return to document contents.

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

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

ColumnType
a sub-section of the
Vector Object section



Address: jragan.com/axledoc_2.htm#70.50.15
-- . --

Syntax:
sReturn = oDataObject.ColumnType( " name " | position_number )

Returns the data type of the specified column. Either a name or position number may be used to specify the column.

Returns an error message if the column is undefined. It is defined after the host app executes a SQL query.

Operations with a remote server may be faster if the "ShowDatasetAttributes" command is used to retrieve all of the attributes in a single return.

Return expected:   Column type.
Return on error :   "Error" message.

Example:
sReturn = oData.ColumnType ( "log_msg" )
sReturn will contain either the column type or an error message.

-- . --

End of the ColumnType sub-section.

Click to return to document contents.

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

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

ColumnWidth
a sub-section of the
Vector Object section



Address: jragan.com/axledoc_2.htm#70.50.17
-- . --

Syntax:
sReturn = oDataObject.ColumnWidth( " name " | position_number )

Returns the maximum width of the specified column. Either a name or position number may be used to specify the column.

Returns zero (0) if the column is undefined. It is defined after the host app executes a SQL query. However, this can be misleading if it is a LONG_STRING data type.

Operations with a remote server may be faster if the "ShowDatasetAttributes" command is used to retrieve all of the attributes in a single return.

Return expected:   Column width.
Return on error :   Minus one (-1).

Example:
sReturn = oData.ColumnWidth ( "log_msg" )
sReturn is provided in case an error is returned.

-- . --

End of the ColumnWidth sub-section.

Click to return to document contents.

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

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

CurrentTupleIndex
a sub-section of the
Vector Object section



Address: jragan.com/axledoc_2.htm#70.50.23
-- . --

Syntax:
sReturn = oDataObject.CurrentTupleIndex

Returns the current cursor location in the dataset. This is the number of the current tuple.

This is initialized to zero and becomes one when a dataset is created. It is changed by the navigation commands.

Return expected:   The tuple index.
Return on error :   Minus one (-1).

Example:
sReturn = oData.CurrentTupleIndex
sReturn will contain either the "Integer" or an error flag.

-- . --

End of the CurrentTupleIndex sub-section.

Click to return to document contents.

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

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

ExecuteSql
a sub-section of the
Vector Object section



Address: jragan.com/axledoc_2.htm#70.50.30

last update**
-- . --

The ExecuteSql command tells AxleBase to execute the SQL(Structured Query Language) statement.

An ExecuteSql command is in the form:
oData.ExecuteSql SQLstring
[ ; APPENDIX( options ) ]
where the SQLstring variable is an ANSI-92 SQL command. (If there is a deviation from the standard, it is explicitly stated in this documentation.)

SQL is a language. The letters stand for Structured Query Language. Although its seemingly illogical convolutions make it detested by professional developers, all serious database managers use SQL for sound theoretical reasons. For database work SQL is the most powerful query language.

This documentation is not intended to be a SQL tutorial. The syntax is presented for each SQL query as a reminder.

If you need more basic assistance, the Axon or CoreReader tool may be of help. It will allow you to build SQL statements in it just by clicking on the data objects. Also, there are many books in print for more advanced assistance.

Caution:
Deferred Returns And Format Specifications :
      Be sure that your commands are thoughtfully controlled. For example, if your query directs a deferred return with "Encryption", then it will be stored as an encrypted datastream, and if you later retrieve it with encryption, you will receive a doubly encrypted unformatted datastream. But perhaps that is what you wanted.

To avoid confusion in a SQL statement, column names should be qualified. The qualification takes the form
          tableName.columnName.
Unqualified column names are assigned to the query's primary table.

See also:
      the "Test SQL" sub-section
      "Command Appendix"
      "ExecuteSql "
      "ExecuteSql Delete"
      "ExecuteSql Insert"
      "ExecuteSql Insert Array"
      "ExecuteSql Select"
      "ExecuteSql Select Into"
      "ExecuteSql Truncate"
      "ExecuteSql Update"
      "ExecuteSql Super-System Extensions"

The command appendix is a non-standard AxleBase extension that should be ignored by beginners. It is not ANSI-92 compliant, but allows use of advanced AxleBase technology.

The following SQL statements are supported with the specified syntax, qualifiers, and sub-commands.

-- . --

End of the ExecuteSql sub-section.

Click to return to document contents.

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

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

ExecuteSql DELETE
a sub-section of the
Vector Object section



Address: jragan.com/axledoc_2.htm#70.50.31

last update**
-- . --

SQL syntax:
oDataObject.ExecuteSql "
DELETE FROM tableName
[ WHERE (selection criteria) [ and (selection criteria) [ and ...] ]
[ ; APPENDIX( options ) ]
"

AxleBase may be configured so that the delete command returns the number of rows deleted from the table. See the "Configuration" chapter for usage.

A delete failure due to a failure of the operation is regarded by AxleBase as an error, and he will stop and return a trappable error message for that type of failure, but the failure to find a row to delete is not an error, so that will not cause an error return.

If the where clause is omitted, all rows are deleted from the table. This is sometimes referred to as a table truncation, although that term is misleading.

A Purge is not needed after all rows are deleted by a single command because the entire data table and file are emptied.

If all rows are deleted from a segment, it is retained. If all rows are dropped from a table, then all segments after the base segment are dropped regardless of table size. When this operation is performed on a "Very Large" table with billions of rows and many segments, the operation will execute deceptively quickly, but will place an inordinate load on the operating system, the hardware and any associated sub-systems. Therefore, if time permits, the "DBA" should inspect the system, the database, and all disk drives afterwards.

See also:
      the "Test SQL" sub-section
      "Command Appendix"
      "ExecuteSql "
      "ExecuteSql Delete"
      "ExecuteSql Insert"
      "ExecuteSql Insert Array"
      "ExecuteSql Select"
      "ExecuteSql Select Into"
      "ExecuteSql Truncate"
      "ExecuteSql Update"
      "ExecuteSql Super-System Extensions"

Caution :
Table Locks :
      - Please remind the builder that he had decided that AxleBase-class data objects and operations should have table-lock handling built into every query.
      However, development stopped before that feature could be implemented.
      If development were to continue, the builder expects the "LockObject" command to be expanded to include tables.
      A query would check for a table lock on every table in the query, and any lock found would precipitate an error chain.
      It would activate a "LockObject" for every table in a SQL statement with an auto release when completed, and a failover for a system crash, anomaly, or an unrecoverable lock clash.
      Jobs: SQL jobs would include the same mechanism.

The command appendix is a non-standard AxleBase extension that should be ignored by beginners. It is not ANSI-92 compliant, but allows use of advanced AxleBase technology.

Return expected:   SQL return.
Return on error :   "Error" message.

Example:
sReturn = oData.ExecuteSql "delete from log where message like '*elise mirage*'"
Example uses sReturn to catch error returns.

-- . --

End of the ExecuteSql DELETE sub-section.

Click to return to document contents.

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

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

ExecuteSql INSERT
a sub-section of the
Vector Object section



Address: jragan.com/axledoc_2.htm#70.50.32

last update**
-- . --

SQL syntax:
oDataObject.ExecuteSql "
INSERT INTO table_name
[ ( column_name [, column_name [ ,...] ] ]
[ VALUES ( variable [, variable [ ,...] ] ) ] |
[ a standard select statement ]
[ ; APPENDIX( options ) ]
"

The ANSI 92 standard allows the entire column name list with its parentheses to be omitted. If the column list is omitted, then the list of values must match all table columns in sequence.

The insert may be of a single row that is created by the list of values. Omitted values will become null.

Multiple rows may be inserted by using a select statement as a clause instead of the values list. The select is a standard select statement as covered in the following ExecuteSql Select section.

Values that are wider than the target column are truncated.

Any insert failure is regarded by AxleBase as an operation error, so he will stop and return a trappable error message for failure to insert a row.

See also:
      "Test SQL" sub-section
      "Command Appendix"
      "ExecuteSql "
      "ExecuteSql Delete"
      "ExecuteSql Insert"
      "ExecuteSql Insert Array"
      "ExecuteSql Select"
      "ExecuteSql Select Into"
      "ExecuteSql Truncate"
      "ExecuteSql Update"
      "ExecuteSql Super-System Extensions"

Caution :
Table Locks :
      - Please remind the builder that he had decided that AxleBase-class data objects and operations should have table-lock handling built into every query.
      However, development stopped before that feature could be implemented.
      If development were to continue, the builder expects the "LockObject" command to be expanded to include tables.
      A query would check for a table lock on every table in the query, and any lock found would precipitate an error chain.
      It would activate a "LockObject" for every table in a SQL statement with an auto release when completed, and a failover for a system crash, anomaly, or an unrecoverable lock clash.
      Jobs: SQL jobs would include the same mechanism.

The command appendix is a non-standard AxleBase extension that should be ignored by beginners. It is not ANSI-92 compliant, but allows use of advanced AxleBase technology.

Return expected:   Nothing.
Return on error :   "Error" message.

Example:
sReturn = oData.ExecuteSql ( "insert into T_LOG select query.save_date, query.dept_share_code, query.owner, query.department, query.description from query where query.owner <> 'mirage'")
sReturn is provided in case an error is returned.

Example ( The ReturnQuantityChanged has been set to yes. ) :
iChanged = 1
iNextGroup = 1
do while iChanged > 0
      iChanged = 0
      sReturn = oDataObject.ExecuteSql ( "insert into T_LOG
      select t_query.save_date, t_query.dept_share_code,
      t_query.owner,t_query.department, t_query.description
      from t_query row ( iNextGroup, 10000 ) )
      if isnumeric( sReturn ) then iChanged = val(sReturn)
      iNextGroup = iNextGroup + 10000
loop
Example uses sReturn to catch error returns.

The following comments and instructions do not apply to normal databases.

Inserts are appended to the last segment in the table. That is true even after deletes because a delete is simply flagged and is removed only by a Purge.

After a purge, empty space is backfilled in the last one hundred table segments. Empty space in segments before the last one hundred will not be backfilled. Therefore, if the "DBA" has cause to delete rows from a "Very Large" table and wants to maintain segment size, then he should purge within every one hundred segments or less as the table grows.

-- . --

End of the ExecuteSql INSERT sub-section.

Click to return to document contents.

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

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

ExecuteSql INSERT ARRAY
a sub-section of the
Vector Object section



Address: jragan.com/axledoc_2.htm#70.50.33

last update**
-- . --

SQL syntax:
oDataObject. ExecuteSQL
INSERT INTO table_name [ ( column_name [, column_name [ ,...] ] ]
ARRAY [ targetLocation ]
( variable [, variable [ ,...] ] )
( variable [, variable [ ,...] ] )
( variable [, variable [ ,...] ] )
[ ; APPENDIX( options ) ]
"

Purpose :
      The arrayed insert is provided for organizations that need to build massive tables. In this command, each element of the array is treated as a row insert. Not recommended for normal database operations.

Servers :
      Server operations can sometimes be made faster with this command because only one command needs to be built, validated, and transmitted for multiple rows.

The arrayed insert is designed primarily for the construction of a "Very Large" table. (This is a non-standard AxleBase SQL extension. Beginners are advised to avoid non-standard SQL in any database manager and to be wary of those brands that do not provide this warning.)

The array consists of a list of value lists. Each element of the list is identified by enclosure in parentheses. Each element of the array will become a row in the table.

The purpose of this command is to increase the speed of large numbers of inserts that automated hosts sometimes require. In standard SQL inserts, the table must be opened, closed, and re-opened for every insert, but for an arrayed insert, the table is opened only once for an array of inserts. This also tends to lessen the stress on the infrastructure during large builds.

A single row insert receives no benefit from an arrayed insert.

Parser Errors :
      The evaluation of the arrayed insert SQL syntax is performed like any other SQL statement. The entire statement, including all of the array, must pass validation before the system will attempt the insert. A failure of any array element to pass the SQL evaluation and validation will abort all of that array's inserts. (The SkipError option has been removed from this command.)

Insert Errors :
      After the SQL evaluation is passed and the insert begins, if one of the inserts fails, then it and all subsequent inserts will abort with a standard error return. If some of the inserts in the array succeeded before it, they will not be rolled back.

Column Names :
      Column names are permitted , but are superfluous and should be omitted to avoid clerical errors. They will be ignored by the system if included. The list of values in every array element must match the actual table columns in sequence using nulls, zeros, or blanks where necessary.

Table Segment Boundary :
      The remaining segment space is checked before beginning the insert.
      If remaining space in the segment is less than the size of the insert, the operation will abort.
      The default segment size of two gig provides a million byte safety margin.
      However, it is possible for another's insert to jump in ahead of yours to cause yours to over-run the segment boundary.
      If the safety margin is inadequate, then the arrayed insert should not be used, or the segment size should be reduced for the duration of the arrayed inserts.

TargetLocation :
      This option is for use by an axsys super-system and is covered in the Advanced Topics addendum to this section.

Recommendation :
      AxleBase generates a load for which most operating systems were not designed. They are inept at file management under that load and it is not unusual to find that the operating system has created a half million file fragments in a two gig file. Defragmenting is not the answer because of the time required for large tables. Therefore, the "DBA" staff may want to build a large table and its indices separately to reduce fragmentation.

Operation Validation :
      In addition to expected tests, the arrayed insert was used by multiple computers and instances to build the 100 billion row table without error or incident. (But the build did take many months of an around the clock run.)

Limits :
      Operational speed is not predictable because of differences in environments. Tests are suggested to determine the ideal array size for your local environment. For example, on the computers in the development environment, using an "AxHandle" host, it was found that fifty-row inserts were faster per row than were hundred-row inserts. Thousand row inserts have been tested in the AxleBase lab.

Formatting :
      Note the formatting in the following examples. It is not required, but AxleBase allows it for human readability. You will find that the AxHandle host formats all of his arrayed inserts to facilitate debugging.

See also:
      the "Test SQL" sub-section
      "Command Appendix"
      "ExecuteSql "
      "ExecuteSql Delete"
      "ExecuteSql Insert"
      "ExecuteSql Insert Array"
      "ExecuteSql Select"
      "ExecuteSql Select Into"
      "ExecuteSql Truncate"
      "ExecuteSql Update"
      "ExecuteSql Super-System Extensions"

Caution :
Table Locks :
      - Please remind the builder that he had decided that AxleBase-class data objects and operations should have table-lock handling built into every query.
      However, development stopped before that feature could be implemented.
      If development were to continue, the builder expects the "LockObject" command to be expanded to include tables.
      A query would check for a table lock on every table in the query, and any lock found would precipitate an error chain.
      It would activate a "LockObject" for every table in a SQL statement with an auto release when completed, and a failover for a system crash, anomaly, or an unrecoverable lock clash.
      Jobs: SQL jobs would include the same mechanism.

The command appendix is a non-standard AxleBase extension that should be ignored by beginners. It is not ANSI-92 compliant, but allows use of advanced AxleBase technology.

Return expected:   Nothing.
Return on error :   "Error" message.

Example:
sReturn = oData.ExecuteSql ( "insert into T_LOG
array
( DateNow(DateTimex) , null, 'kate', 'SERVER4', 'Log size was voided')
( DateNow(DateTimex) , null, 'kate', 'SERVER4', 'max setting was 100000' )
( DateNow(DateTimex) , null, 'kate', 'SERVER4', 'truncated log' ) " )
Example uses sReturn to catch error returns.

Example:
Another engine is building the same table on a different location computer.
sReturn = oData.ExecuteSql ( "insert into T_LOG
array \\server15\db15
( DateNow(DateTimex) , null, 'kate', 'SERVER4', 'Log size was reset')
( DateNow(DateTimex) , null, 'kate', 'SERVER4', 'max setting was 100000' )
( DateNow(DateTimex) , null, 'kate', 'SERVER4', 'truncated log' ) " )

Example:
The "Testing AxleBase" sub-section discusses the use of the arrayed insert by the AxHandle tester app.

The following comments and instructions do not apply to normal databases.

The arrayed insert is expected to be used principally in environments that can bring an axsys to bear on a table construction. Engines might be building the table on the construction face while other engines work behind it to construct the indices. See the Advanced Topics chapter for a discussion of axsys.

The highest speeds are obtained by dedicating engines to build in their own databases and, afterwards, moving those segments into the main table. That also segregates the build operations from production and is usually used in the AxleBase test lab. However it requires experienced personnel and close monitoring of the operations, so the targetLocation parameter has been provided to add speed.

The optional targetLocation parameter allows multiple engines to work on the same table at high speed with reduced contention. Ordinarilly, an arrayed insert writes into the last available segment or into the next mapped location. If the target location is present in the SQL statement, then that engine will insert only into that location.

The optional targetLocation parameter must be used with a table write map. AxleBase will look for a location in the map that matches his targetLocation and will build in that location.

If there is a space in the targetLocation string, then the string must be enclosed by a balanced set of apostrophes.

Suggestion :
      To take advantage of the targetLocation option, assign a different spindle or storage medium to each engine to reduce hardware thrashing from disk contention.

Caution :
      The target location option is designed to span multiple locations. Only the left-most portion of the locations in the write map are checked against the target location, which allows an entire server to be targeted. For example, the target location \\server83\db\ will write to all map locations that begin with \\server83\db\.
      It will write to no other mapped locations.
      This feature allows multiple "Instances" to use the same write map while avoiding disk contention.
      Each instance will create and fill its own segments.
      A downside to this is that it can produce partially filled segments that will never be filled thereafter.
      It can also produce unsequenced segment numbers in each location, which can become extremely trying for the DBA.

Backfilling :

Inserts are usually appended to the last segment in the table. That is true even after deletes because a deleted row occupies the space until it is removed by a Purge.

Purged tables are backfilled in the last one hundred table segments. Empty space in segments before the last one hundred will not be backfilled. Therefore, if rows are deleted from a very large table and the DBA wants to maintain segment size, then he should purge within every one hundred segments or less as the table grows.

All engines in an axsys see all segments, and when started, they will all backfill the table as needed. That can create unusual and unforeseen contention on startup. That contention can be prevented by using a write map with target locations in the arrayed inserts. Each engine will then work only in its own locations.

-- . --

End of the ExecuteSql INSERT ARRAY sub-section.

Click to return to document contents.

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

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

ExecuteSql SELECT
a sub-section of the
Vector Object section



Address: jragan.com/axledoc_2.htm#70.50.35

last update**
-- . --

Compressed SQL syntax:
oDataObject.ExecuteSql "
SELECT columnNames
FROM tableName
[ WHERE conditions ]
[ ORDER BY columnNames ]
[ ; APPENDIX ]
"

Expanded SQL syntax:
oDataObject.ExecuteSql "
SELECT
{ * | table.* | table_alias.* |
table.column_name | table_alias.column_name } |
function(table.column_name) | function(table_alias.column_name) }
[ [AS] column_alias ]
} [,...n]
FROM table_name [ [AS] table_alias ]
[ [ INNER | { { LEFT | RIGHT | FULL } [OUTER] } ] JOIN
table_name | table_alias
ON table|alias.column = table|alias.column ]
[ WHERE (selection criteria) [ and (selection criteria) [ and ...] ]
[ ORDER BY { [table|alias.]column } [column, ...n] [ ASC | DESC ] ]
[ GROUP BY parameter [,...n] ]
[ HAVING condition ]
[ ; APPENDIX ( ) ]
"

( See the Functions and Logical Operators section of this chapter for useful functions. )

The select statement is more complex than is documented here. Please refer to other authorities for details. AxleBase supports those constructs and options unless specifically noted otherwise.

AxleBase processes the select statement from left to right including all joins and wheres.

Caution :
Table Locks :
      - Please remind the builder that he had decided that AxleBase-class data objects and operations should have explicit table-lock handling built into every query.
      However, development stopped before that feature could be implemented.
      If development were to continue, the builder expects the "LockObject" command to be expanded to include tables.
      A query would check for a table lock on every table in the query, and any lock found would precipitate an error chain.
      It would activate a "LockObject" for every table in a SQL statement with an auto release when completed, and a failover for a system crash, anomaly, or an unrecoverable lock clash.
      Jobs: SQL jobs would include the same mechanism.

Aliasing :
      Although it is a canonical ANSI specification, some popular database managers cannot use the AS keyword. Therefore, AxleBase accepts aliasing with or without the AS.

Optional Names :
      Column qualification is always recommended. Forgetting a comma, for example, may tell AxleBase to alias a name.

SQL Functions :
      Sum(), Min(), Max(), Avg(), Count(), STD()
      See the "SQL Summary Functions" sub-section.

Join Types :
- Inner :   Return only matching pairs of rows.
              Discard others.
- Left :     Return inner joined rows and
              left rows that had no match.
- Right :   Return inner joined rows and
              right rows that had no match.
- Outer :   Return Inner Joined rows and
              rows in either table that have no
              match in the other table.
- Full :   Same as Outer join.

Non-Standard Features :
      "row", "segment", "appendix", "CacheReturn", "node", "queryId", "workArea"
      That list consists of non-standard AxleBase extensions to the SQL syntax to manage "Very Large" queries. Each is covered in depth in its sub-section of the Functions and Logical Operators section of this chapter.
      ( Beginners are advised to avoid non-standard SQL in any database manager and to be wary of those brands that do not provide this warning.)

Caution :
Deferred Returns And Format Specifications :
      Be sure that your commands are thoughtfully controlled. For example, if your query directs a deferred return with "Encryption", then it will be created and stored as an encrypted datastream. Then, if you later retrieve it with encryption, you will receive a doubly encrypted datastream. But perhaps that is what you wanted.

See also the "Data Transfer Protection Technology" sub-section for guidance.

Sounds Like :
      Available condional selects include "SOUNDS LIKE" that uses the original soundex algorithm. (Courtesy of the American taxpayer like so much of what the world takes for granted.) To use this feature, the condition must be
      where value sounds like 'mary'
The negation is
      where value not sounds like 'mary'
This feature necessarily delivers approximate results. Remember that it was designed for standard American English pronunciation. It can increase processing time tremendously for large files.

Joins :
      Joins are supported by AxleBase in the From clause and not in the Where clause. Wheres are supported in the Where clause and not in the From clause. The joins that are shown above are supported. (This comment is due to some brands of database managers not observing this standard.)

Order By :
      - The Order By clause specifies a sort of the return.
      - Sort order may be ascending, descending, or blank. A blank defaults to ascending. It goes at the end of the sort clause.
      - A table's column may be used in a sort without being declared in the select clause.
      - The sort specification may include any number of columns, but a very long specification may become slow.
      - Multiple columns are sorted from left to ritght so that each column is sorted within the column to its left.
      - Any column sequence may be specified, and the sort will proceed from left to right. The return sequence will remain as specified in the select.
      - Small sorts are quickly done in RAM. Large sorts are done on disk, so twenty million rows of two gigabyte rows can be very slow.
      - See the WorkArea SQL extension for large data return help.

Variable Delimiters :
      - The industry's standard variable delimiter is the apostrophe. It is not a single quote.
      - AxleBase can be reconfigured to use almost any non-standard "Delimiter" character(s). (See the "Configuration" chapter.)
      - Where a value contains a delimiter, see the Delimiter Escape sub-section.

Row And Segment Specs :
      - Caution : In a query, do not place row or segment clauses in the command appendix.
      - In other operations, the row and segment specifications are placed within the command appendix to separate them from standard SQL and commands. However, in a query, the system needs a way of identifying the table for each row and segment clause, so the row and segment clauses in a select must be placed immediately after each table.

See also:
      the "Test SQL" sub-section
      "Command Appendix"
      "ExecuteSql "
      "ExecuteSql Delete"
      "ExecuteSql Insert"
      "ExecuteSql Insert Array"
      "ExecuteSql Select"
      "ExecuteSql Select Into"
      "ExecuteSql Truncate"
      "ExecuteSql Update"
      "ExecuteSql Super-System Extensions"

The command appendix is a non-standard AxleBase extension that should be ignored by beginners. It is not ANSI-92 compliant, but allows use of advanced AxleBase technology.
      These appendix options may be used in a Select in any sequence.
      CacheReturn()
      QueryId( idString )
      WorkArea( path location )
      Node( parameters )
      Encrypt
      Protocol( specification )
      Row( tablename, startRow, quantity )
      Segment( tablename, startSegment, quantity )
      Test as a "Boolean".
      Comments( comments )
      Query values take highest precedence except encryption.
      A return protocol can be specified for an immediate return.
      A return protocol cannot be specified for a deferred return.
      A protocol can be specified during the retrieval.
      See the protocol attribute section for discussion.

Extreme Conditions Support:
      See the Data Retrieval Protection Technology

Return expected:   SQL return.
Return on error :   "Error" message.

Example:
sReturn = oData.ExecuteSql "SELECT * FROM LOG "
Example uses sReturn to catch error returns.

Example:
sReturn = oData.ExecuteSql ( "select
t_relations.table_name_one,
t_COLUMNS2.col_size as col2_size
from ( t_relations left outer join t_columns AS t_columns1
on t_RELATIONS.column_name_one = T_COLUMNS1.column_name )
left join t_COLUMNS AS t_COLUMNS2 on
T_RELATIONS.column_name_two = t_COLUMNS2.column_name
where T_RELATIONS.table_name_one = t_COLUMNS1.table_name
and T_RELATIONS.table_name_two = T_COLUMNS2.table_name " )

Example:
sReturn = oData.ExecuteSql ( "select avg ( PERSON_AGE ), min ( PERSON_AGE ), sum ( income ) from T_PEOPLE ")
Example uses sReturn to catch error returns.

Example:
sReturn = oData.ExecuteSql ( "select count(*) from T_Customers ")
Example uses sReturn to catch error returns.

-- . --

End of the ExecuteSql SELECT sub-section.

Click to return to document contents.

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

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

ExecuteSql SELECT INTO
a sub-section of the
Vector Object section



Address: jragan.com/axledoc_2.htm#70.50.36

last update**
-- . --

SQL syntax:
oDataObject.ExecuteSql "
SELECT column1[, column2[, ...] ]
[ INTO targetTable | targetFile [ IN 'externalLocation' ] ]
FROM sourceTable [ selection criteria ]
[ APPENDIX( options ) ]
"

The INTO clause is an optional clause in the SELECT statement that was covered in the preceding section.

Deviation From Standard SQL :
      AxleBase deviates from the standard in this command.
      Standard usage returns a tuple into variables.
      But AxleBase creates either a table or a file and inserts an entire dataset into it.

Column[n] are the names of the columns to be copied into the new table. TargetTable is the name of the table that will be created. SourceTable is the name of the table(s) from which rows are selected.

Target Table :
      Query appendix will be ignored for target configuration.
      Column attributes will be taken from the source columns.
          names
          datatypes
          widths
      Use the 'as' sql option to change the column name.
      Type will be fixed width.

The AxleBase version of this command can be especially useful for temporary work tables. The INTO clause may NOT be used with an existing target table. AxleBase will create the target table. Data can be inserted into an existing table by using the INSERT statement with its sub-select clause

Notice that the command actually creates a new table. That table will be catalogued by AxleBase, so it can be used like any other table after the select, thereby supporting unattended system operation. Caution: Your database can become cluttered with temporary work tables if you are not a tidy person.

See also:
      the "Test SQL" sub-section
      "Command Appendix"
      "ExecuteSql "
      "ExecuteSql Delete"
      "ExecuteSql Insert"
      "ExecuteSql Insert Array"
      "ExecuteSql Select"
      "ExecuteSql Select Into"
      "ExecuteSql Truncate"
      "ExecuteSql Update"
      "ExecuteSql Super-System Extensions"

Caution :
Table Locks :
      - Please remind the builder that he had decided that AxleBase-class data objects and operations should have table-lock handling built into every query.
      However, development stopped before that feature could be implemented.
      If development were to continue, the builder expects the "LockObject" command to be expanded to include tables.
      A query would check for a table lock on every table in the query, and any lock found would precipitate an error chain.
      It would activate a "LockObject" for every table in a SQL statement with an auto release when completed, and a failover for a system crash, anomaly, or an unrecoverable lock clash.
      Jobs: SQL jobs would include the same mechanism.

The command appendix is a non-standard AxleBase extension that should be ignored by beginners. It is not ANSI-92 compliant, but allows use of advanced AxleBase technology. The appendix clause can alter characteristics of the new table or file.

Export :
      The optional IN clause allows the dataset to be written into a file in any valid location outside the database.
      Column separators, column type, row terminator, return type, etc. will be the database standard or can be changed in the query "Command Appendix".
      Non-standard returns are not currently supported.

See also : the "Export" command, the previous Select sub-section, and the Data Retrieval Tools compendium.

Return expected:   Nothing.
Return on error :   "Error" message.

Example inserting data into a temporary work table:
sReturn = oData.ExecuteSql ( "select * into temp_table from setting where owner = 'elise mirage'")
Example uses sReturn to catch error returns.

Example exporting to a file named work_text:
sReturn = oData.ExecuteSql ( "select * into work_text in ' c:\program files\AxHandle ' from setting where owner = 'elise mirage'")
Example uses sReturn to catch error returns.

-- . --

End of the ExecuteSql SELECT INTO sub-section.

Click to return to document contents.

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

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

ExecuteSql TRUNCATE
a sub-section of the
Vector Object section



Address: jragan.com/axledoc_2.htm#70.50.38

last update**
-- . --

Caution :
      All are advised to avoid this command.
      This command is not standard SQL and is available only to comfort those who are accustomed to Oracle. It will delete all rows from a table of any size.

This command is no faster than the standard delete.

(The truncate command is a non-standard Oracle SQL extension. Beginners are advised to avoid non-standard SQL in any database manager and to be wary of those brands that do not provide this warning.)

See also:
      the "Test SQL" sub-section
      "Command Appendix"
      "ExecuteSql "
      "ExecuteSql Delete"
      "ExecuteSql Insert"
      "ExecuteSql Insert Array"
      "ExecuteSql Select"
      "ExecuteSql Select Into"
      "ExecuteSql Truncate"
      "ExecuteSql Update"
      "ExecuteSql Super-System Extensions"

Caution :
Table Locks :
      - Please remind the builder that he had decided that AxleBase-class data objects and operations should have table-lock handling built into every query.
      However, development stopped before that feature could be implemented.
      If development were to continue, the builder expects the "LockObject" command to be expanded to include tables.
      A query would check for a table lock on every table in the query, and any lock found would precipitate an error chain.
      It would activate a "LockObject" for every table in a SQL statement with an auto release when completed, and a failover for a system crash, anomaly, or an unrecoverable lock clash.
      Jobs: SQL jobs would include the same mechanism.

The command appendix is a non-standard AxleBase extension that should be ignored by beginners. It is not ANSI-92 compliant, but allows use of advanced AxleBase technology.

Example:
sReturn = oData.ExecuteSql ( " truncate table connections")
Before execution, it is converted to the correct:
o.ExecuteSql ( " delete from connections " )
Example uses sReturn to catch error returns.

-- . --

End of the ExecuteSql TRUNCATE sub-section.

Click to return to document contents.

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

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

ExecuteSql UPDATE
a sub-section of the
Vector Object section



Address: jragan.com/axledoc_2.htm#70.50.39
-- . --
^

This advanced technology has been temporarily

moved off line during the documentation editing.

-- . --

End of the ExecuteSql UPDATE sub-section.

Click to return to document contents.

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