CVW: Core Database Reference

Reference For Extending The CVW Core Database

What is a Core Database?

A core database is one consisting only of the system objects necessary for the cvw to function. It contains all the code of the cvw server necessary to interact with the clients. The objects in a core database are "system" objects that either perform functions necessary for the proper function of the cvw, or provide a generic class of object that other data objects are derived from. For instance, there is a generic note, a generic document, and so on. They define what characteristics and behavior those types of objects will have. Any objects created by users are derived from some generic object in the core database.

How do I make an object part of the Core Database?

In order to be part of the core database, an object must be defined on #0, the system object, and must have an object number under #1001.

The CVW reserves all object numbers under #1001 for use as core objects. Those objects below #1001 that have not been defined remain as "placeholder" objects. To make a new core object, change one of the placeholder objects into the new core object. This involves changing the placeholder’s parent to be the parent of the new core object, and then copying and recreating any verbs or properties (see example below). The parent of the new core object should already be a core object, if it is not, then repeat this step for the parent, and its parent, and so on, until you reach an object that is already part of the core. For cleanliness, core objects are created sequentially, so if the last core object is #150, then placeholder #151 should be used to create the next core object.

Once the object is successfully created with object number below #1000, you should define it on #0. To do this, you create a property on #0 whose value is the object number of your new core object. The core object can later be referenced by the name of the property on #0, rather than as a hard coded object number.

Here is an example:

I want to make the following object a core object:

>@d #6365:
Grep utils (#6365) [ ]
Owned by Dee (#1341).
Child of Generic Feature Object (#71).
Location Dee (#1341).
#6365:parse_flags Dee (#1341) rxd this none this
#6365:@vsearch Dee (#1341) rxd any any any
#6365:@psearch Dee (#1341) rxd any any any
#6365:@pgrep Dee (#1341) rxd any any any
#6365:change_verbs Dee (#1341) rxd any any any
----------------------------- finished -------------------------------

So I alter the next available placeholder and replicate the data and functionality:

>#160
=> #160 (Placeholder #160)
>@chparent #160 to #71
Parent changed.
>@rename #160 to Grep Utils
Name of #160 changed to "Grep Utils", with aliases {"Grep Utils"}.
>@describe #160 as A feature that enables searching of the database for particular verbs or properties.
Description set.
>@copy #6365:parse_flags to #160
Use of @copy is discouraged. Please do not use @copy if you can use inheritance or features instead. Use @copy carefully, and only when absolutely necessary, as it is wasteful of database space.
#160:parse_flags code set.
>@copy #6365:@vsearch to #160
Use of @copy is discouraged. Please do not use @copy if you can use inheritance or features instead. Use @copy carefully, and only when absolutely necessary, as it is wasteful of database space.
#160:@vsearch code set.
>@copy #6365:@psearch to #160
Use of @copy is discouraged. Please do not use @copy if you can use inheritance or features instead. Use @copy carefully, and only when absolutely necessary, as it is wasteful of database space.
#160:@psearch code set.
>@copy #6365:@pgrep to #160
Use of @copy is discouraged. Please do not use @copy if you can use inheritance or features instead. Use @copy carefully, and only when absolutely necessary, as it is wasteful of database space.
#160:@pgrep code set.
>@copy #6365:change_verbs to #160
Use of @copy is discouraged. Please do not use @copy if you can use inheritance or features instead. Use @copy carefully, and only when absolutely necessary, as it is wasteful of database space.
#160:change_verbs code set.

Then I define the object on #0:

>@corify #160 as grep_utils
Grep Utils has no :init_for_core verb. Strongly consider adding one before doing anything else.

Tips regarding Core Objects

There are two important verbs that core objects might require. The first is an init_for_core verb. The init_for_core verb will be executed whenever a core database is created. This is where core clean up should go. For instance, if a core object maintains a counter property, it will more than likely need to be reset whenever a new core is created. This is done by defining an init_for_core verb and, in the verb code, setting the property back to its original value. Common sorts of clean up performed in init_for_core verbs are emptying or initializing list properties, renaming objects to a generic sort of name, or altering any properties whose value may be specific to the MOO and therefore require a more generic value to be useful elsewhere. This is especially important if the property contains the object number of a non-core object, which may not exist in another MOO, or may be a completely different kind of object.

The other verb required for certain core objects is a recore_lines verb. This verb enables the object to write itself out during an update process. For instance the $note object (#9) must know how to write out information specific to notes, such as text. That way, when a user creates a note (a child of $note) and enters some text, the note will be written out and no data will be lost when the database is updated. Generally a core object requires a recore_lines verb if 1) it is the base class for objects that users will create and 2) it defines a new property (not inherited from its parent) that its children will use and need to save across an update (e.g. a text property, or a path property, or a docid property, etc).

On rare occasions, a core object itself will be modified by users, and will then need to be written out as well. For instance the $login_message (#104) is tailored to each MOO and ought to be saved during an update, so the administrator does not have to re-tailor it after each update. In this case, the $login_message is a child of $note, which already knows how to write out the text. However, if the $login_message defined a new property to store the message, rather than using the predefined text property, then the $login_message would require a recore_lines verb to write out that property, even though it is not a base class for objects.

It is important to note that if a property is added to a core object, you must reevaluate the need for an init_for_core and/or recore_lines verb. If the object already had such a verb, it may need to be modified to include data for the new property. If the object did not have the verb, then it may need to be added, based on the requirements described above (i.e. does the new property need to be reset for a core, or does its value need to be saved during an update).

Note: When the core database is being created, object relocation (putting a core object in a certain place) is done in $wiz:mcd_2. It is rarely necessary to place a core object anywhere other than #-1, and when it is done, the new location must also be a core object. However, if the need arises insert the move statement in the relocation section of $wiz:mcd_2.

How do I make a Core Database?

The process of actually making a core database is rather simple. Make a separate copy of your database, since the core making process will destroy all non-core objects. Then start the copy and log in as admin (#2), or whatever user is #2, if you have renamed the account. You must log in specifically as #2 because another user cannot make a core even if they have admin privileges. Once connected, type "make-core-database" (without the quotes). To ensure against accidental execution, you will be prompted to enter the command again followed by a specific number. After you do, the database will do the rest, and will provide frequent status updates throughout the process. When it is finished (usually a couple minutes), you will be told to type "@shutdown" to shutdown the new database and save it to disk. The resulting output file is a core database.

During the core making process it is possible you may see a traceback. This is a known race condition. It occurs because when object A is being destroyed it tries to notify other objects of its changing status. However the objects it tries to notify are themselves being destroyed, so if the notifications are arranged just right, you will get a traceback. The transmittal of this status info isn’t important since all objects will be wiped out anyway. The tracebacks can be safely ignored and will not impede the process in any way.

Tips for making a Core Database

The following is a checklist to use as a guideline when making a core database:

run "@egrepcore #[3-9]" & "@egrepcore #[1-2][0-9]" (without quotes) to check for hard-coded object numbers in the core

This check will display any hard-coded object numbers in your code. Generally hard-coded object numbers (except #0, #1, & #2) are a bad idea. If the object numbers are core objects, then the reference is probably safe, but unclean nevertheless. If the object numbers are not core objects, they will probably not be the same object (and might not even exist) in another moo and will therefore break the code.

check newly created core objects to see if they require a recore_lines (if they are a base class for things users will create) or an init_for_core (if they have properties that need to be reset to defaults)

These verbs are discussed above, and should be created as the objects are created, but a quick check before making a core cannot hurt.

consider whether any old core objects have acquired new properties that require adding recore_lines or init_for_core verbs (or require modifications to any existing recore_lines or init_for_core verbs)

Again, these verbs are discussed above, and should be created or modified when the property is added, but a quick check before making a core cannot hurt.

add any necessary steps to $wiz:mcd_2 for placing core objects or other initialization or clean up stuff

This verb was mentioned briefly above, and will probably not require modifications.

make sure new core has proper version number

The core version is defined by #0.version in the form of a string. You can set this value before or after the core making process, or at another other time. Before distributing a core, however, you ought to verify that it is the intended version number.

make sure all protocol versions are up to date

It is always a good idea to check that the core speaks the proper protocols and that the versions are correct before distributing it. For more information about protocols and versioning, see the MCP documentation.

make sure $latest_jcvw is the right version

The CVW PC client reads this value to inform users if there is a more recent version available. This version should be set to the compatible version of the PC client, and updated as necessary when the database or client changes.

Last update: 13 October 2000

This work, including the source code, documentation and related data, is placed into the public domain.
The original author is The MITRE Corporation.

THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, AS TO THIS SOFTWARE, OR TO THE ACCURACY, CAPABILITY, EFFICIENCY, OR FUNCTIONING OF THIS SOFTWARE OR ANY DERIVATIVE WORK OR OTHER ITEM MADE, USED, OR SOLD THAT INCORPORATES THIS SOFTWARE. THE AUTHOR OF THIS SOFTWARE ASSUMES NO RESPONSIBILITY FOR ANY CONSEQUENCE RESULTING FROM THE USE, MODIFICATION, OR REDISTRIBUTION OF THIS SOFTWARE.

Information in this document is subject to change without notice.
Other products and companies referred to herein are trademarks or registered trademarks of their respective companies or mark holders.