Previous Up Next

Chapter 6  The ConceptBase.cc Server

The ConceptBase.cc server (CBserver) offers its services via a TCP/IP port to client programs. The main services are to TELL or UNTELL O-Telos objects and to ASK queries to the database. The operations are called by clients (for example, the user interfaces described in section 8). An arbitrary number of clients can connect to a CBserver.

The CBserver is started1 by a command line

   cbserver <params>

assuming that the installation directory of ConceptBase.cc is added to the search path of executable programs. If it is not on the search path, then simply change the current directory to the installation directory of ConceptBase.cc or use its absolute path of the cbserver script.

6.1  CBserver parameters

The following parameters are available for the ’cbserver’ command:

-d dbdir
Set database dbdir to be loaded. If the database does not exist, it is created and initialized with the O-Telos pre-defined objects. The database is maintained as a directory. Setting the database is mandatory except when the update mode is set to nonpersistent (see below). You cannot start two concurrent servers which use the same database directory. To avoid this case, a file OB.lock is created in the database directory when the first server is started. If the server crashes during its execution, the file OB.lock will still exist in the directory. Before you restart the server, you might have to remove this file manually.
-db dbdir
Like -d but also sets the load/save/views directories to dbdir, i.e. the CBserver will automatically maintain the module sources in dbdir and also materialize the selected queries in the same directory. See section 5.10 for details.
-new dbdir
Like -d but deletes any existing database at location dbdir before it creates and initializes it.
-u updatemode
controls update persistency. The allowed values are persistent and nonpersistent. If no database is provided by parameter "-d", then the default update mode is set to nonpersistent. Otherwise, the default is persistent. In nonpersistent mode, all updates are lost after the ConceptBase server is stopped. In persistent mode, updates are stored in the files of the database and will be available for future sessions.
-U untellmode
controls the way how UNTELL is executed by the server. The allowed values are verbatim and cleanup (default). In verbatim mode, the UNTELL operation will only untell the facts directly described by the O-Telos frame being submitted as argument. In cleanup mode, UNTELL will also try to remove the instantiation to the O-Telos system classes Individual, Attribute, InstanceOf and IsA. By doing so, UNTELL behaves inverse to the TELL operation. More details are explained in subsection 6.9.
-port portnr
sets the TCP/IP socket portnumber for client connections to the CBserver. The value portnr must be between 2000 and 65535. If there is already a process using the portnumber, the CBserver will abort. The default value for the portnumber is 4001.
-p portnr
is the same as "-port portnr". Deprecated since it conflicts with a predefined command line parameter of SWI-Prolog.
-version
display version info and exit.
-help
display list of CBserver options and exit.
-license
display license and exit.
-t tracemode
sets the tracemode of the CBserver. It is one of silent, no, minimal, low, high, veryhigh. The tracemode determines the amount of text displayed by the server during its execution. The tracemode does not influence the function but is used for debugging. The default tracemode is set to minimal (only display CBserver interface). The tracemode low will configure the CBserver to trace the CBserver interface calls plus answers, and the tracemode no virtually disables tracing. The tracemode silent is even surpressing the message ’CBserver ready’ when starting up the CBserver. The tracemode high and veryhigh are useful for debugging the system. In these two modes, an unlikely fatal signal like division by zero will not directly abort the CBserver process but start a debug dialog. Enter "h" for options to diagnose the problem in collaboration with the ConceptBase developers.
-c cachemode
turns on the query cache to allow recursive query evaluation. The value cachemode is one of off, transient, and keep (default). In transient mode the cache is emptied before each transaction. In keep mode, the cache is emptied when the maximum number of entries in the cache is exceeded or an update has invalidated the cache. Further details are explained in section 6.7.
-o optmode
controls the optimizer for rules, constraints and queries. The value optmode is one of 0 (no optimization), 1 (structural optimization by exploiting builtin O-Telos axioms), 2 (optimizing join order), 3 (combines 1 and 2), or 4 (combines 1 and 2 with trigger pruning). Default and recommended is 4.
-r secs
automatically restarts the CBserver after a crash, or when it was started with option -sm slave and the last client exits. The value secs specifies how many seconds to wait before restart. You may want to use this option in a multi-user setting, where the CBserver runs on a different machine that the user clients. The -r option must be handled with great care since it can easily lead to an infinite loop of restarts, e.g. when a database file is corrupted. In such cases you might have to reboot the whole computer!
-s securitylevel
configures the access control mechanism of ConceptBase. The value 0 means that no access control is employed. Any user can ask, tell, untell, retell any object in any module. You can also untell objects defined in a super-module. Level 1 (default) provides a very basic protection: one can only untell objects when the are defined in the current module. This prevents in particular undesired deletions of objects defined in the System module. Level 2 fully enables access control. First, untelling of objects must happen in the module where the object has been defined. Second, any transaction submitted by a user to the CBserver is checked against the permission rules as defined in section 5.7. Enable access control when you use ConceptBase in a multi-user setting and you want to avoid errorneous interferences between different users.
-e maxerrors
sets the maximum number of errors to be displayed to a ConceptBase.cc client within one transaction. The value -1 means that no restriction is applied. Set to 0 to surpress any errors message and to a positive number to limit the displayed errors messages to that number. A low positive number can speed up the communication between ConceptBase client and server if a lot of error messages are generated. The default is 20.
-cc ccmode
(predicate typing) controls to which extent the CBserver applies strict typing of attribution predicates (x m y) occurring in the membership constraints of query classes. If the mode is set to strict (=default), attribution predicates without a unique concerned class2 shall not be accepted. If the mode is set to extended, the search for concerned classes shall include subclasses (see section 2.2.7). If the mode is set to off, ConceptBase.cc also accepts queries with unstrictly-typed attribution predicates. The strict mode is preferable since it avoids certain semantic errors. Deduction rules and integrity constraints may never violate the predicate typing condition, even if the mode is set to off. An example for a query using non-strict predicate typing is available from the CB-Forum, see link.
-mu mumode
(multi-user mode) specifies whether the CBerver should run in multi-user mode (value enabled) or in single-user model (value disabled). By default, the multi-user mode is enabled, allowing multiple users with different user names to connect to the CBserver. In single-user mode, only clients started by the same user (identified by her name) can connect to the CBserver. The single-user mode is recommended if you want to block other users from logging into your CBserver. Since the test is done only on the user name, a malicious attacker could use your user name for an account on another computer and then successfully log into your CBserver. Use Internet firewalls to protect against such attacks. If you specify an administrator user (option -a), then this use can always connect to the CBserver.
-v vmode
controls whether view maintenance rules are generated (vmode=on) or not (vmode=off). View maintenance rules are used to keep a ConceptBase.cc view up-to-date upon changes to the object base. Default value for vmode is off.
-mc maxcost
this parameter defines the maximum cost level for a predicate in a binding path that is used to compile a meta formula (see section 2.2.9). The evaulation of a binding path yields fillers for the meta variables. Set maxcost to 10 if such a predicate should have about one free variable. Set it to 100 if if may have two free variables. Default is 100. The higher the number, the more candidate paths are generated, increasing the likelihood that a binding path is found. On the downside, a high value increases the compile time of meta formulas.
-pl pathlen
sets a maximum length for binding path candidates. In principle, the number of candidates can explode with the path length. Like the previous parameter, the path length influences the ability of ConceptBase.cc to compile meta formulas. The default value is 5. If you set the value to 0, then no meta formula can be compiled.
-im imax
sets the maximum number of iterations used to re-order attribution predicates with one free variable. Evaluating such predicates first can lead to faster elimination of free variables and thus lead to better query and ECA performance. The default value is 3.
-eca emode
controls the ECA sub-system. Possible values are unsafe (ECArules are evaluated without safeguarding recursive deductive rules), off (ECArules are not evaluated, even if some are defined), and safe (ECA rules are evaluated with safeguarding recursive rules; this is the default). Use the mode unsafe if none of your ECArules calls recursive predicates on the newest database state. This may lead to a limited speed-up.
-eo eomode
controls the optimization of conditions of ECArules. Possible values are on (default) and off. The optimization is done by a re-ordering of predicates in the condition. Hence, you only want to turn of optimization to gain full control over the order of evalution in ECA conditions.
-load dir
specifies the directory from which the CBserver will load module sources at start-up time. The module sources must have file names starting with System and file type sml. Typically, they are generated via the -save flag in the preceding session of the CBserver. The default is none, i.e. no module sources are loaded at CBserver start-up.
-save dir
specifies the directory into which to save certain textual excerpts of the database, in particular module listings. The parameter has the default value none, which disables the saving function. Currently, the CBserver only saves module listings. Each module is stored in one file with file type sml. The directory dir must exist. The module listing is performed when the CBserver is shut down (complete module tree is listed), or when a client tool logs out (home directory tree of the client tool is listed). The module listings uses the set module directive to enable the import of the file to the right module location. See also section 5.9 for details.
-views dir
specifies the directory into which the results of certain queries are materialized. See section 5.10 for details.
-ms sep
specifies the module separator to be used for saving module listings and views. If the separator is set to ’-’ (default), then all module sources and views are stored at the top level directory. If the module separator is set to ’/’, then the files are stored in a deep sub-directory structure that mirrors the module structure.
-mg mgmode
specifies whether module listings are generated with separators "{---}" for each transaction occurring in the module (option split) or without such separators (option whole). The default is split. The split option better supports cases where metaformulas are defined and used in the same module.
-rl rlmode
controls the way how the CBserver creates labels for generated formulas. The default value is on, instructing the CBserver to find a readable label for the generated formula. It typically consists of the labels of the participating metaclass attributes occuring in the metaformula. If set to off, the CBserver will just take a system-generated label that contains a unique identifier. This is slightly less readable (if you want to inspect the generated formulas) but safe against certain possibilities of assigning the same label twice.
-ia tmax
sets the maximum number of hours during which a client should interact with the CBserver to be regarded as active. Negative values are interpreted as ’infinity’. This parameter is only used when a CBserver uses the -sm slave and -r options, or the -g public option. The default value for tmax is 2.0 hours.
-sm servermode
sets the server mode. Possible values are master (default) and slave. In slave mode, the last client that leaves the CBserver will also shutdown the CBserver, provided that the CBserver and the client were started by the same user. This option is useful when a CBserver is only needed while still clients are registered. A master CBserver must always be stopped explicitly.
-st stratmode
enables or disables the rule stratification test. Possible values are on (default) and off. If enables, then the query evaluator shall dynamically test whether stratification violations occur. They shall then be reported as an error. Disable the test, if you are sure that the answers are correct even though a stratification violation occurs.
-g cmd
provides a special command to the CBserver. There are currently three such commands. The command nolpi instructs the CBserver to ignore any plug-in file (see section F). The command public configures the CBserver as a public CBserver (see 6.6). The command exit instructs the CBserver to exit immediately after start-up. This can be useful to combination with the option -views, -db and -save to materialize some excerpts from a stored database.
-a user
designates user as ’administrator’ of this CBserver. For the time being this just gives the right to shutdown the CBserver. By default, the user who started the CBserver is its administrator. This user shall also keep the right to shutdown the server, even when another user is the designated administrator. If you specify the user name with host, e.g. billy@myhost, then only the user billy on host myhost is recognized as additional administrator.


If a CBserver is started without any parameter, then the update mode shall be set to nonpersistent, the trace mode to no, multi-user mode is disabled, and the server mode to slave. The other parameters are set to their defaults. Such a CBserver is useful as companion of tools that need it only while they are running.

   cbserver

A ConceptBase client running on the same computer will then connect to this CBserver, when it uses ’localhost’ as host and 4001 as port number. Since the CBserver runs un slave mode, it will shut down when its client disconnects.

6.2  ConceptBase under Windows 10

The CBserver is only compiled for Linux architectures. This means that user of other platforms must rely on a Linux system to utilize ConceptBase. The traditional way is to start the CBserver on such a Linux system and then connect to it, possibly using a so-called public CBserver (see section 6.6). Since April 2017, this detour is no longer required for users of Windows 10 (64bit, Creators Update). This version of Windows is capable to let Linux programs run under the ’bash’ utility, which is basically a whole Linux system under Windows that realizes calls to the Linux API by hooks to the Windows API. Hence, it is not a virtual machine, it lets you run the Linux (64bit) variant of the CBserver natively on Windows 10.

To enable the Linux capability on Windows 10, follow the instructions at link. Note that you must have installed Java (64bit) on your Windows machine, not Java (32bit) to take full advantage of this feature. You can check whether your Java is 64bit by calling the following command in a Windows command window.

   java -d64 -version

Users of older Windows versions and of other operating systems can continue to use the public CBserver (see section 6.6) to take advantage of ConceptBase.

6.3  Database format

A ConceptBase database is a directory that contains at least the following files:

The database files may only be updated via the ConceptBase server. Their initial state is bootstrapped from textual Telos frames that define the pre-defined objects of O-Telos. Since the pre-defined objects can change from version to version, we cannot guarantee binary compatibility of ConceptBase databases. You can easily export the textual definitions from a databases via the -save option. Those definitions can then be imported to the new ConceptBase version. The database directory may contain further text files with filetype ’lpi’. These are Prolog plugins loaded at startup time, see also section F.

6.4  Modifying the system database

A new database is created from the database lib/SystemDB in your ConceptBase installation directory. The System database contains exactly the objects of the root module System. They include for example the definitions of the objects Proposition, Individual, Attribute, InstanceOf, and IsA. Further the objects Class, QueryClass, Function, ECArule, Module and many more are defined that are needed to formulate queries and to use the capabilities of the system.

Whenever a new database is created, the files from this System database are copied into the new database directory. This allows experienced ConceptBase users to adapt the System database to their needs. Just start a ConceptBase server with

cbserver -d $CB_HOME/lib/SystemDB -s 0

Replace $CB_HOME by the path to your ConceptBase installation directory. Then start a CBIva user interface, connect to the CBserver and switch to the module System. Assume you want to predefine the class Container and declare a Model as subclass of Container:

Container with
  attribute
     contains: Proposition
end
Model isA Container end

You can also add rules and constraints about containers, e.g. that containers may not contain themselves. A more significant extension would be to add active rules to the system database. For example, the active rules in CB-Forum at link changes the semantics of the UNTELL operation. Such definitions are subsequently included in any new database that you create. Be careful with deleting system objects. The code of the CBserver relies on the existence of certain system objects.

6.5  Tracing and restarting


The trace of the CBserver can be saved by redirecting its output, e.g.

cbserver -r 10 -port 4444 -t high -d MYDB >> mylogfile.log

The CBserver can also be started directly from the ConceptBase.cc User Interface (see section 8) and most parameters can be specified interactively. The command line version is recommended when one CBserver serves multiple users or when user interface and server shall run on different machines. The parameter -r 10 instructs the CBserver to restart after 10 seconds if a crash has occurred.

A special error message during the startup of the CBserver is the following:

### FATAL ERROR:
Application is locked by hostname, PID 1234 
### CBserver aborted

This messsage is printed if there is still a file with the name OB.lock in the database directory (option -d). The OB.lock file should avoid that two servers are using the same database directory. The file may be left over of a previous CBserver if the server was not stopped correctly (e.g. aborted by Ctrl-C or it crashed). If you get this error message, make sure that there is no other server running that uses this directory and then delete the file OB.lock. Then, the CBserver should start correctly.

6.6  Public CBservers

A public CBserver is a ConceptBase server that is accessible from the whole network. As such this is a property that any CBserver has, except when the multi-user capability is disabled, or when your firewall prevents external access.

If you work with an existing database, you may want to specify some access rights rules like suggested in section 5.7. We neglect them in this simple example. Now, start the public CBserver with suitable parameters under Linux/Unix:

cbserver -r 2 -a jonny -g public -ia 0.5 -u nonpersistent -d MDB &> log.txt &

The option -g public enables the slave mode implicitely and tells oHome as an instance of AutoHomeModule. The combination of the slave mode and the option -r instructs CBserver to stop and restart when the last client exits. The update mode is nonpersistent. As a consequence, the restarted CBserver will use the unchanged state of MDB. This is useful, if you want to provide the service of CBserver to a larger group of (anonymous) users. They can log in with a client, operate on the database in nonpersistent mode and eventually leave the CBserver. When the last active client3 leaves the CBserver, then CBserver will freshly start up after 2 seconds. Due to the option -u nonpersistent user-defined objects are only stored at the public CBserver while there are still active clients enrolled to the public CBserver.

The parameter -a sets the administrator user of the public CBserver. This user is allowed to shutdown the CBserver from a client. The auto home feature will assign different users to individual workspaces. Unless you introduce access rights (and enable them via the CBserver option -s 2) the users can also manipulate the modules of other users. However, the CBserver is restarted whenever the last client logs off. Hence, the definitions of different users are not permanently stored on the CBserver. The parameter -ia used here instructs the CBserver to regard a client as active of it had its last interaction within 0.5 hours. Clients that were inactive for a longer time will not prevent the CBserver from restarting when another (active) client logs off the CBserver.

Consider the following alternative command to start a public CBserver:

cbserver -t no -r 2 -a jonny -g public -ia -1 -d ALLDB &> /dev/null &

Here, the updates are stored persistently in the database ALLDB. Changes to modules are not lost when the last active client leaves the CBserver. There is no log file created as well. The option ’-ia -1’ used here instructs the CBserver to regard any client as active, regardless of how long ago its last interaction occurred.

Configure the CBIva interface to use the public CBserver via the variable PublicCBserver. It can be set by the menu item "Options/Edit Options Manually" of CBIva, see section 8.4. A value different from none enables the use of the public CBserver by CBGraph. You can optionally append a port number like "cbserver.acme.com/4002". The default value for the port number is 4001. Installations of ConceptBase on platforms, for which no binaries of the CBserver exist, may use a default public CBserver. This is the case OS-X and older versions of Windows4.

Don’t forget to save the options after changing the variable.

The best way to interact with a public CBserver is to use graph files, see section 8.2.3. Assume that a public CBserver is running on host cbserver.acme.com. and that cbserver.acme.com was configured as the public CBserver to be used. Then, calling

cbgraph graph1.gel 

will connect to the public CBserver instead of ’localhost’. The port number for the connection is taken from the graph file. Do not forget to save the graph file before exiting CBGraph if the public CBserver was started in non-persistent mode. If you subsequently open the graph file, it will attempt to connect to the same host. You can force it to attempt the connection to localhost instead by

cbgraph -host localhost graph1.gel 

6.7  The tabling subsystem

Since version V5.2.4 ConceptBase.cc features a new query evaluation method, which uses a so-called tabling cache to store intermediate results of predicates that are called during the top-down (SLDNF) query evaluation. Assume, for example, that an employee ’bill’ has two projects ’p1’ and ’p2’. Then, the result of a predicate ’(bill hasProject x)’ with variable x would be the set {(bill hasProject p1),(bill hasProject p2)} consisting of facts. We call this fact set also the extension of the predicate.

After a completed predicate evaluation, the tabling cache of the predicate holds its extension. Tabling speeds up query evaluation and prevents infinite loops when ConceptBase.cc evaluates recursive queries and deductive rules. Essentially, the tabled evaluation allows to compute dynamically stratified semantics of the Datalog database underlying ConceptBase.cc. Plenty of examples for recursive rules and queries are provided in the online ConceptBase Forum.

The CBserver provides three tabling cache modes to control the behavior during query evaluation:

-c off
In this mode, the cache is completely disabled. Use this mode when your models do not include recursive rules. The mode is only provided for backward compatibility and has no advantages.
-c keep
The cache is only emptied when necessary, in particular when the cache has been invalidated by an update to the database, or when the maximum number of facts in the cache is exceeded. The maximum number is currently set to 20000. Exceeding the maximum is not an error. It only indicates that the cache is marked for being emptied. If necessary, the cache emptying takes place before a transaction. The keep mode is on average consuming more main memory than the transient mode but speeds up response time enormously in case of re-use of query results. The ’keep’ mode is the default mode for tabling.
-c transient
The tabling cache is emptied before each transaction (ask, tell, untell, retell). A subsequent query is always evaluated starting with an empty cache. This mode is somewhat ’safer’ than the ’keep’ mode since it starts each query with an empty cache state. While the answer to a query is in principal independent from the cache mode, the cache mode has a certain influence on the persistence of objects created within a transaction. Specifically, results of arithmetic expressions computed during one transaction shall be removed after the transaction when the cache mode is ’transient’. In cache mode ’keep’, these objects continue to exist and are visible to future transactions.

ConceptBase will only call tabled evaluation for deductive predicates. Other predicates are evaluated by the regular SLDNF engine of the underlying Prolog engine. By default, the tabling cache mode is activated in mode keep. Some statistics on cache usage are written to the terminal window of the ConceptBase server when the tracemode has been set to veryhigh.

Acknowledgements: The techniques for the tabled query evaluator of ConceptBase.cc are inspired by the ’tabled evaluation’ [SSW94, CW96]. We do however not delay the evaluation of negated predicates but rather re-order them at compile time to guarantee that all variables are bound at call time. Tabled evaluation is also implemented in XSB [link] and DES [link].

6.8  Database persistency

The default update mode is ’persistent’. In persistent mode, all changes to the database are written to the file system at the directory specified in the parameter ’-d’. Persistent mode is suitable when a CBserver runs for a longer period of time and is directly updated by application programs. If ConceptBase.cc is used for testing and modeling purposes, the update mode ’nonpersistent’ is an interesting alternative. We discuss two scenarios for the nonpersistent mode and one for the persistent mode.

Scenario 1: Single-user modeling. When a user needs to model a certain application domain with classes and meta classes, he usually works with external Telos files (aka source models, file extension ’.sml’). These files can include comments like usual with program source code. The recommended mode here is ’-u nonpersistent’ without specifying a database. The user can load the source models into such a non-persistent server and make corrections to the source files in case of errors or design changes. Here, ConceptBase is mostly used to check and analyze the models. Recommended options:

cbserver -u nonpersistent -mu disabled

Scenario 2: Lab assignments. Assume that a teacher wants students to exercise a certain modelling task using ConceptBase.cc. Then, he would prepare some Telos files with necessary definitions (e.g. some meta classes) and load them into a persistent ConceptBase server. After that, he can restart the ConceptBase server in non-persistent mode on the same database created before. Student can then work on their extensions while the state of the database can easily be set back to the original state defined by the teacher. The module system of ConceptBase.cc can be used to support multiple students to work on the same server without interfering with each other, see section 5. Recommended options:

cbserver -d MYDB -s 2 -mu enabled -u nonpersistent

The second scenario might also be useful in modeling. If there are some parts that are regarded as stable, the modeller can decide to make them persistent and only add/modify those Telos models that are still subject to change. In particular for large Telos models, this strategy saves time. Note that the updates by the users are lost when the non-persistent CBserver is stopped. This might be useful, if you want to re-use the same initial database MYDB several times, e.g. for different user groups.

Scenario 3: Project work. Here the students work for several days on a given task. Changes shall not be lost. The use of the -db option will not only store the database in binary form but also store the source code of all modules as text files in directory MYDB. Recommended options:

cbserver -db MYDB -s 2 -mu enabled 

If ConceptBase.cc is used in a multi-user setting, then one can combine the update mode with the module feature (see section 5). In this scenario, multiple users access the same CBserver. A common super module (e.g. the module oHome) carries the common objects of the users. Each user can be assigned to her own hown module (a sub module of the common super module) and create and update objects in this workspace without interfering with other users. If several groups of users shall share their definitions, then they would be assigned to the same home module. The home module may have sub modules for testing and releasing definitions. By employing access rights to modules, one can also design which user has which read/write permissions. The builtin query listModule allows to save the contents of a module to a Telos source file (see section 5.8).

6.9  The UNTELL operation

ConceptBase.cc realizes the concept of a historical database. The TELL operation submits O-Telos frames to the CBserver. The CBserver extracts the ’novelty’ of the submitted frames and translates it into a set of P-facts to be stored in the object store. Any P-fact has a so-called belief time associated to it (see section 2.1). The belief time is an interval (t1,t2) whose left boundary t1 is the time point when the P-fact was inserted to the object store, i.e. the time when the transaction was executed that led to the insertion of the P-fact. The right boundary t2 specifies the time point after which the CBserver assumes the P-fact to be not true anymore. It is initialized with ’Now’ when the P-fact is created. This symbolic value is interpreted as the current time. You may also interpret such a time interval to be right open.

The UNTELL operation terminates the belief time of P-facts specified in an O-Telos frame. The value ’Now’ is replaced by the time5 when the UNTELL operation is executed.

From the user’s perspective, a TELL operation is about creating some objects and the UNTELL operation is about deleting them6. Many users expect the UNTELL operation to be symmetric to the TELL operation, i.e. untelling a frame that has been told before should remove the frame completely. This is however not the case for the following reasons:

The last reason is most significant in preventing symmetry. As an example consider the O-Telos frame (referred to as frame 1).

  bill in Employee with
    name
     bname: "William"
  end

ConceptBase.cc will recognize that bill is an individual and that bill!bname is an attribute. This information is attached internally to the P-facts, more precisely, it is derivable from the structure of the corresponding P-facts. Assume that you started a CBserver with untell model verbatim (see below). When you ASK the CBserver for the frame of bill after the TELL operation on frame 1, you will get frame 2:

  Individual bill in Employee with
    attribute,name
     bname: "William"
  end

Hence, the instantiation to the builtin classes Individual and Attribute is added to the frame. If we submit the original frame 1 to an UNTELL operation, ConceptBase.cc assumes by default that only two facts should be untold:

  1. The instantiation of bill to Employee.
  2. The instantiation of the attribute bill!bname to its attribute category Employee!name.

As a consequence, the object bill and its attribute continue to exist after the UNTELL on frame 1. It would look like (frame 3):

  Individual bill with
    attribute
     bname: "William"
  end

Only by untelling this frame 3 as a second operation or by untelling the completed frame 2, the object bill and its attribute bill!bname shall be made historical.

This assymmetry of TELL and UNTELL is regarded by some ConceptBase.cc users as unnatural behavior. They expect that an UNTELL is also supposed to affect the objects themselves, not just their instantiation to classes. To support those users, we provide a so-called untell mode (see parameter -U in the list of CBserver command line parameters). The untell mode verbatim will cause ConceptBase.cc to behave as explained above. The mode cleanup (default) will take care to remove the objects themselves provided that they have no other instantiations to classes except instantiation to the four builtin classes Individual, Attribute, InstanceOf, and IsA. Furthermore, no other object may be linked to the object subject to be untold.

6.9.1  Cascading UNTELL

You can use ECArules to realize a cascading UNTELL, i.e. if an object is deleted then all its links to other objects are deleted as well, leading to potential follow-up deletions. The required ECArules are provided in link. You only need to add the ECArules to your database to enact the cascading UNTELL. You should be careful with using the cascading UNTELL. For example, untelling a system class will also untell all instantiations to it. Use the CBserver option -s 1 to prevent such undesired deletions.

6.10  Memory consumption and performance

ConceptBase.cc stores objects in a dedicated object store maintained in main memory. A P-fact P(o,x,n,y) consumes about 800 bytes of main memory. That means that one can store roughly 1 million P-facts in 1 GB of main memory. A typical Telos frame is stored with roughly 10 P-facts. Hence, 1 GB of main memory allows you to store around 100.000 Telos frames. On 32 bit CPUs, this results in a maximum of roughly 400.000 frames that can fit into 4 GB of addressable main memory. This restriction virtually vanishes with 64 bit CPUs.

A single TELL/UNTELL operation submitted to the CBserver should not contain more than about 2000 frames (at about 5 attributes per frame). Otherwise, the compiler can run out of stack memory.

The raw performance of the object store, i.e. the time needed to reconstruct a frame for a given object identifier, is virtually independent from the number of P-facts that it stores. However, if you have defined many rules or integrity constraints, the performance may well degrade significantly with the number of stored P-facts. The same holds for queries. We tested the response times for standard queries such as computing the transitive closure in relation to varying database sizes. Results indicate that ConceptBase apparently approximates in many cases the theoretic optimum.

The performance of the active rule evaluator (section 4) is currently rather limited. We measured around 100 rule firings per second. This can be a performance bottleneck when many active rules are being processed.

6.11  The Java API to the CBserver

The application programming interface (API) to the ConceptBase server (CBserver) is realized by the Java class LocalCBclient. Most (Java) application programmers presumably only need the simple String-based part of LocalCBclient to interact with a CBserver. LocalCBclient uses socket-based data streams to realize the communication. We define here the methods of this String-based API. If the argument starts with an "s", then the data type is String. If it starts with an "i", then the data type is int.

LocalCBclient cbClient = new LocalCBclient();
answer = cbClient.connect(sHost, iPort, sTool, sUser);
answer = cbClient.disconnect();
answer = cbClient.pwd();
answer = cbClient.mkdir(sModule);
answer = cbClient.cd(sModule);
answer = cbClient.tells(sFrames);
answer = cbClient.untells(sFrames);
answer = cbClient.asks(sQuery,sFormat);
answer = cbClient.asks(sQuery);


Below is the listing of the Java program TinyClient.java that uses the String-valued API:

import i5.cb.api.*;
public class TinyClient {
  private static LocalCBclient cbClient = null;
  public static void main(String argv[])  {
    String answer;
    cbClient=new LocalCBclient();
    answer = cbClient.connect("cbserver.acme.org",4001,"TinyClient",null);
    answer = cbClient.tells("Employee in Class end");
    answer = cbClient.asks("get_object[Employee/objname]");
    System.out.println(answer);
    answer = cbClient.disconnect();
  }
}

You need to compile the Java program with the cb.jar library. This is available from the ConceptBase installation directory (referred here as CB_HOME). To compile the Java program call

  javac -classpath $CB_HOME/lib/classes/cb.jar TinyClient.java

Before running the client, make sure that the CBserver runs on the specified Linux computer (here "cbserver.acme.org") under the specified port number (here 4001), and that this port number is accessible from your client computer. You may want to configure that CBserver as a public CBserver (see section 6.6) to have a save way to connect your Java program to it.

The Java program can then be started under Linux as follows:

  java -classpath $CB_HOME/lib/classes/cb.jar:. TinyClient

Under Windows, you should use:

  java -classpath c:\conceptbase\lib\classes\cb.jar;. TinyClient

The Java source code TinyClient.java and for a more elaborate example SimpleClient.java are included in the directory examples/Clients/JavaClient of your ConceptBase installation directory.


1
You can also start the CBserver from within the ConceptBase.cc user interface CBIva. Details are in the installation guide distributed with ConceptBase.cc and in section 8.3.
2
The concerned class is a consequence of the predicate typing condition of section 2.2. You can roughly compare it to typing of variables in programming languages.
3
An active client is a client whose last interaction with the CBserver was less than a certain number of hours ago, specified with the CBserver parameter -ia.
4
Windows 10 (64bit) Creators Update has the ability to activate a Linux sub-system which can then be used to start CBserver transparently. If you had previously used a public CBserver under Windows 10 and now want to utilize a local CBserver, then reset the variable PublicCBserver to none.
5
ConceptBase takes the system time using timezone Coordinated Universal Time (UTC) of the computer on which it is running and rounds it to milliseconds. The time is captured when the transaction is initiated, i.e. all P-facts told or untold in the transaction will use that transaction time.
6
’Deleted’ objects can however be recovered by setting the so-called roll-back time before an ASK transaction is issued. Only ASK transaction are allowed on historical database state. It makes little sense to update a historical state. That would be ’falsifying’ the history of stored P-facts.

Previous Up Next