Difference between revisions of "Cyc Administrator Handbook/Routine Maintenance Tasks"

Latest revision as of 02:40, 29 May 2019

Prev: Managing Databases Home:Cyc Administrator Handbook Next: Backup and Restore

This page is based on the original document Enterprise Cyc Administrator Handbook at https://www.cyc.com/documentation/enterprise-cyc-administrator-handbook/ There is no intent to infringe on Cycorp's Copyright.
It is Copyright (c) Cycorp 2019
Cycorp's address is 7718 Wood Hollow Drive Suite 250 Austin, TX 78731 USA
mailto:info@cyc.com   Main Phone: 512.342.4000

Maintaining your License Information

Most Cyc license keys are temporally constrained.
Starting a Cyc server with an expired license key produces an error message of the following form: “Your current Cyc license is no longer valid. …”
For more information on obtaining a valid license for your Cyc server, contact http://www.cycorp.com .

Installing your Cyc License Key

To install your valid Cyc license key, follow these steps.

Open ${CYC_BASE_DIR}/init/jrtl-release-init.lisp with a text editor.

Locate the line that starts (csetq *master-license-key* "XXXX-, where XXXX is a four-digit group of hexadecimal digits.

If this is an initial installation, the key string will be "0000-0000-0000-0000-0000";

if not, it will be your institution’s prior license key, enclosed by double quotes.

Replace the key value inside the double quotes by your new valid license key.

Save the file.

Notice that changing the Cyc license key requires a Cyc server restart to take effect.

Reporting Bugs

Enabling Java Assertions

Many of the consistency checks in Cyc are implemented using a feature of the Java programming language called assertions - not to be confused with Cyc knowledge base assertions.
By default, Java assertions are disabled, meaning that their presence incurs no slow down.
However, in the context of trying to report a bug it is useful to enable Java assertions and accept the performance hit.
Enabling and disabling assertions requires that additional options be passed on the command line to the Java virtual machine that hosts the Cyc server at system start-up time;
consult your Java SDK's documentation for more details.
The place to add additional command line options is the ${CYC_BASE_DIR}/bin/cyc-runner.sh script, which is the funnel through which all run scripts go.
Enabling assertions under Windows 7 is currently not supported.

An Example for Enabling Java Assertions

Note: The following uses the SubL read loop to evaluate SubL expressions that form part of the example.

Consider the expression (namestring-preds-of-string "Lenat")]], which performs a reverse-lookup on lexification predicates to determine where a specific lexical entry  is coming from (here for Cyc's "father"  Doug Lenat (#$Lenat)).

Passing a non-string value to this API method –
e.g. 212–produces a Java stack trace similar to the following:

212 is not of type: SEQUENCE.

 java.lang.Exception
  at  com.cyc.tool.subl.jrtl.nativeCode.subLisp.Errors.possiblyCallErrorHandler ( Errors.java:381 )
  at  com.cyc.tool.subl.jrtl.nativeCode.subLisp.Errors.error ( Errors.java:174 )
  at Cyc/Java/method/com.cyc.tool.subl.jrtl.nativeCode.subLisp.Errors.error (Cyc/Java/source_file/Errors.java:154 )
  at Cyc/Java/method/com.cyc.tool.subl.jrtl.nativeCode.type.number.AbstractSubLNumber.toSeq ( AbstractSubLNumber.java:583 )
  at  com.cyc.tool.subl.jrtl.nativeCode.subLisp.Sequences.find ( Sequences.java:222 )
  at  com.cyc.cycjava.cycl.nl_trie.nl_trie_single_token_stringP ( nl_trie.java:9443 )
  at  com.cyc.cycjava.cycl.nl_trie.nl_trie_string_tokenize_multiple ( nl_trie.java:9425 )
  at  com.cyc.cycjava.cycl.nl_trie.nl_trie_search_int ( nl_trie.java:4843 )
  at  com.cyc.cycjava.cycl.nl_trie.nl_trie_search_case_insensitive_internal( nl_trie.java:4699 )
  at  com.cyc.cycjava.cycl.nl_trie.nl_trie_search_case_insensitive ( nl_trie.java:4710 )
  at  com.cyc.cycjava.cycl.nl_trie.nl_trie_search ( nl_trie.java:4624 )
  at  com.cyc.cycjava.cycl.nl_trie_accessors.gated_nl_trie_search ( 
 nl_trie_accessors.java:3213 )
  at  com.cyc.cycjava.cycl.nl_trie_accessors.nl_trie_namestring_preds_of_string  ( nl_trie_accessors.java:982 )
  at  com.cyc.cycjava.cycl.lexicon_utilities.namestring_preds_of_string  ( Cyc/Java/source_file/lexicon_utilities.java:9414 )


Notice in the stack trace that the namestring-preds-of-stringX method directly or indirectly invoked several stack frames before the problem was noted and progress checked. This is due to the fact that, by default and for performance reasons, the  namestring-preds-of-string method assumes that its arguments are of the correct type.

However, by enabling assertions for the class   com.cyc.cycjava.cycl.lexicon_utilities, the invalid argument can be caught earlier. Editing the ASSERTS_FLAG variable in ${CYC_BASE_DIR}/bin/cyc-runner.sh to specify the class for which to enable assertions
(i.e. ASSERTS_FLAG=-ea:com.cyc.cycjava.cycl.lexicon_utilities ) results in the top level method catching and reporting the problem.

 java.lang.AssertionError: 212
   at  com.cyc.cycjava.cycl.lexicon_utilities.namestring_preds_of_string ( lexicon_utilities.java:9412 )

Starting and Stopping TCP/IP Services

Note: The following discussion assumes familiarity with the way the Network Services on a Cyc server are configured; for background information, see the sections above. For a description of the API that assists in managing TCP/IP service, see this section above.

For many routine maintenance tasks, such as backup, it is important to isolate the Cyc server and to deny all users access. Disabling TCP/IP services is an effective way of isolating the server, restricting all access to the console interface. In the same way, it is important to resume network connectivity once such routine maintenance tasks have completed. Notice that the disabling of TCP/IP services only affects future connections, but does not terminate existing connections.

Stopping TCP/IP Services

The following sequence of commands is to be issued from the console interface, since that is the only command service that is unaffected by the TCP/IP services.

Use the (ALL-TCP-SERVERS) command to determine which TCP/IP services are active on this Cyc server.

Disable all TCP/IP services with the command (DISABLE-ALL-TCP-SERVERS). Alternatively, you can disable the services individually using the API method (DISABLE-TCP-SERVER service-descriptor), where service-descriptor is one of the service descriptors enumerated in the table in the section on enablement above.

For example, to disable the HTTP service, use (DISABLE-TCP-SERVER :HTTP).

Verify that (ALL-TCP-SERVERS) now returns NIL.

Use the (SHOW-PROCESSES) command to review the still active SubL processes on the Cyc server. Existing connection threads will look as follows:

Socket Connection Handler: Socket[addr=/10.1.1.143,port=57278,localport=3602]

Depending on your system policy, you may wish to extend a grace period before removing any of the existing connections.Programmatically, you can do so with the (SLEEP sec) API method, which will block execution for sec seconds. For example, to extend a grace period of two minutes, you could use a SubL expression such as (SLEEP (* 2 60)), since a minute has sixty seconds.

Use the (show-processes) command to determine whether any connection handlers remain.

If necessary, terminate any lingering processes using the (KILL-PROCESSES-WITH-SUBSTRING substring) API method, in this case (KILL-PROCESSES-WITH-SUBSTRING "Socket Connection Handler").

Starting TCP/IP Services

The following sequence of commands is to be issued from the console interface, since that is the only command server that will be available when the TCP/IP services have been disabled.

Determine which TCP/IP services are to be active on the Cyc server in question.That information will either be in init/port-init.lisp for ResearchCyc, or in init/release-specific-init.lisp for OpenCyc and Enterprise Cyc.

For each desired TCP/IP service, determine the service descriptor and the API for computing the port from the table in the section on enablement above.

Use the [[Cyc/subl-function/enable-tcp-server|(ENABLE-TCP-SERVER service-descriptor (compute-port-api)) expression to re-enable each desired TCP/IP service in order.For example, to enable the HTTP service that drives the Cyc Browser, use (ENABLE-TCP-SERVER :HTTP (HTTP-PORT)).

Use (ALL-TCP-SERVERS) to verify that all desired TCP/IP services have been enabled.

Use (SHOW-PROCESSES) to verify that a server process has been launched for each desired TCP/IP service.

For example, the SubL process for accepting HTTP connection will appear as follows:

Socket Server (port: 3602 handler: HTTP-SERVER-HANDLER)