The overall environment for a given Octopus database is defined by parameters in an [OCTOPUS instance-name] section of the nucleus.ini file, as described below. Configuration settings for multiple Octopus instances can be specified in a single nucleus.ini file; in this case, each Octopus instance has its own section.
The Octopus section header must contain the keyword OCTOPUS followed by a name for the Octopus instance, as follows:
If instance-name is not the same as the database instance name that clients will specify when connecting to Octopus, the DatabaseName parameter must be included in the OCTOPUS section.
The table below lists the parameters that must be included in the main Octopus sections of the nucleus.ini file.
list of the names of the classes of service for the Octopus instance,
separated by commas, ordered from the lowest to the highest level of processing
operating in Public Update mode, the last
class in the list is automatically defined as updatable. When the LoginClass=TRUE
parameter is set, the first class in the list is reserved for processing
client database login requests.
For example: LOGIN,LIGHT, HEAVY, UPDATE
When configuring multiple instances of Octopus on a single computer, remember that using the same Class names for the different instances will result in the Class definitions being shared. To avoid this, use specific Class names for each instance.
The name of the SAND CDBMS connection that clients will specify when connecting to the Octopus instance.
The client-side nucleus.ini file must contain a [CONNECTION
connection-name] section with a matching connection name and
containing a Port specification that matches the value for Port
in the OCTOPUS section of the server-side nucleus.ini file.
directory location of the primary database file (.n00 file)
The parameters listed below can also be included in the OCTOPUS sections of the nucleus.ini file. If these parameters are not included, the default values are used.
When AutoStartup=TRUE, the Octopus instance will be started automatically by the Octopus daemon/service when the system starts. If AutoStartup=FALSE or the parameter is absent, the instance must be started manually using the OCTOPUS command.
Specifies the network ID name or IP address corresponding to the network adaptor on which Octopus will listen for connection requests from clients. If the machine identified by the network name has multiple network interfaces (IP Addresses) the server/agent process will be bound to all IP addresses. Alternatively, if a single IP address is specified, the server/agent process will be bound only to that IP address. Multiple IP addresses can be specified, in which case they must be separated by commas.
Time in seconds before a server will become available for a request. This time is linked to the last Octopus activity of a particular user.
|BoundUserTimeOut=||Time in seconds before an OctoRefresh
or COMMIT (in Public Update mode) will be executed on a server with bound
statements. This time is linked to the last Octopus activity of a particular
The maximum amount of virtual memory (in megabytes) that will be allocated for database operations.
name and location of the file to which cumulative Octopus statistics are
directory specified by the DatabasePath parameter
The database instance name that clients will specify when connecting to the Octopus instance.
Default: instance-name from the OCTOPUS section
The location of the Delta Files to which changes to the database will be written.
Default: . (current directory)
time in seconds before cancellation of an Octopus fetch operation (involved,
for example, when scrolling through result sets with SAND Analytic Explorer
or Microsoft Access). This allows the database version to be refreshed
if necessary. This parameter applies only when a client is connecting
Sets the scale for the results of integer division. By default, if a division operation contains an INTEGER, SMALLINT, or UNSIGNED value as the divisor and dividend, the resulting value is an integer, and any decimal portion of the result is truncated. When the IntegerDivisionScale parameter is set to a positive number, integer division will instead return a value rounded to the specified number of decimal places.
The IntegerDivisionScale parameter must be set to a non-negative integer number n, where n is the number of decimal places that will be returned by integer division. For instance, IntegerDivisionScale=1 means that results have one decimal place, IntegerDivisionScale=2 means two decimal places, and so on to a maximum of 50 decimal places. However, for large IntegerDivisionScale values, the actual maximum scale depends on the number being divided. For A divided by B:
(Required if LDAP is used) The format of the base "distinguished name" message string that will be sent to an LDAP server. It has the following form:
The "ou" parameter specifies an organizational unit, such as the country code. The "dc" parameter(s) specify each component of the domain, delimited by commas. For example, "uk.myhost.com" would be represented as "ou=uk,dc=myhost,dc=com".
(Required if LDAP is used and LDAPROLE is not set) The list of LDAP group and SAND database role bindings in the following format:
Multiple binding pairs must be separated by semicolons, as in this example:
Beyond simple one-to-one bindings, some logical construction is permitted in the string, allowing logical OR/AND group memberships to determine bindings. For instance, membership in both group 1 and group 2 can be defined as a requirement for binding to authorization X. Similarly, membership in either group 1, group 2, or group 3 can be defined as a requirement for binding to authorization Y. The logical OR is represented by a comma ( , ), while the logical AND is represented by a plus sign (+). Logical evaluation is performed left-to-right, although this order can be altered with parentheses, since logical expressions within parentheses are evaluated first.
In addition, a binding can be limited to a particular SAND database by including @database immediately after the binding pair.
There is also a way to specify a default binding if no other binding applies to the LDAP user. This is done by specifying *:user last in the LDAPBINDINGS list (where * represents "all Active Directory groups").
The following table summarizes the special characters permitted in the LDAPBINDINGS string:
If an LDAP user belongs to more than one group, the first binding in the list that applies to the user (reading from left to right) will be used.
|LDAPCNAlias=||Specifies the LDAP attribute that stores the user name. This parameter should only be set if the standard CN (Common Name) attribute is not used to store the user name.|
A comma-separated list of one or more Active Directory domains (for example, "dev,qa,mkt,sales"). The domain associated with the user's system login name is checked against this list. If it is not found, the LDAP authentication will fail.
If this parameter is omitted, user domain verification is not performed.
(Required if LDAP is used) The host name or IP address, and optionally the port number, for the LDAP server(s). If the port number is omitted, the default port is assumed (389, or 636 for SSL).
The format of the LDAPHOST string (or "URL") is as follows:
If Secure Sockets Layer (SSL) is enabled, specify "LDAPS" instead of "LDAP":
Multiple or redundant LDAP servers can be specified in the LDAPHOST parameter simply by separating the URLs with commas. For example:
The LDAP servers are read from left to right in the LDAPHOST list. If the leftmost server is not available, the next one in the list will be tried, and so on until an available LDAP server is found.
Sets the user authentication mode. There settings are:
Note that both LDAP modes can be enabled by including both "LOGIN" and "OPEN" for the LDAPMODE parameter, separated by a comma (for example, "LOGIN,OPEN"). In this case, the user can enter either their user name and password, or the "_me_" constant.
If "OPEN" is specified and "LOGIN" is not, only users that connect with "_me_" will be accepted.
Sets the full path, including file name, of the system's LDAP library, in case the default library will not be used. This parameter applies only to operating systems other than Windows and AIX.
Default: libldap.so (in the LDLIBRARYPATH location)
|LDAPRole=||(Required if LDAP is used and LDAPBINDINGS is not set) The name of the LDAP attribute containing the SAND database role.|
|LDAPServicePassword=||The LDAP server password for the user specified with the LDAPSERVICEUSER parameter.|
|LDAPServiceUser=||(Required if LDAP is used and LDAPMODE=Open) Specifies a third party "service user" that will perform the LDAP authorization lookup on behalf of the client user. Typically, this is a specialized user defined on the LDAP server with limited privileges beyond authorization lookup.|
name and location of the Octopus log file (.otl).
specified by the DatabasePath parameter
When set to TRUE, Octopus reserves the first (leftmost) class in the Classes list for processing database login requests. This guarantees that clients will be able to log in to the database even when the system is very busy. A corresponding Subclass should be configured with a single OctoEng and a small Cache value.
(UNIX only) Sets the maximum amount of virtual memory (in megabytes) that the OctoEng's will use. If MaxVMem is not set, a server will use the environments hard ulimit setting to determine its virtual memory limit, based on the hard ulimits relation to the minimum memory requirements for the server (Cache value + 1024 MB).
If the MaxVMem setting is less than the Cache value + 1024 MB (1 GB), it is automatically set to Cache + 1 GB. If the MaxVMem setting is greater than the hard ulimit setting, it is automatically set to the hard ulimit setting. If MaxVMem is not set and the hard ulimit setting is unlimited, MaxVMem defaults to Cache + 1 GB.
The maximum virtual memory settings are summarized in the table below:
Minimum: Cache value + 1024 MB
The maximum size of the ODDB instance's temporary Delta File, in which database changes are recorded, specified as as a percentage of the database size. The default setting for ODDBMaxDeltaFileRatio is 0 (disabled), meaning the ODDBMaxDeltaFileSize parameter is used instead to specify the maximum Delta File size. If values for both ODDBMaxDeltaFileRatio and ODDBMaxDeltaFileSize are specified, and the ODDBMaxDeltaFileRatio value is not 0, the ODDBMaxDeltaFileRatio value is used.
The maximum size (in megabytes) of the ODDB instance's temporary Delta File, in which database changes are recorded, specified in megabytes. If values for both ODDBMaxDeltaFileSize and ODDBMaxDeltaFileRatio are specified, and the ODDBMaxDeltaFileRatio value is not 0, the ODDBMaxDeltaFileRatio value is used.
|NonPersistentChangeUsers=||(Private Update mode only, for non-persistent updates)
A comma-separated list of user names with non-persistent update capabilities.
|NonPersistentChangeUsersConfigFile=||(Private Update mode only, for non-persistent updates)
The name of a file containing a list of user names (one per line) with non-persistent update capabilities. This parameter overrides the NonPersistentChangeUsers parameter, if both are set.
(Private Update mode only, for non-persistent updates)
Setting this parameter to FALSE enables non-persistent
updates via OctoEng's in any class other than the Login class. The default
setting (TRUE) permits non-persistent updates only on OctoEng's in
the heaviest class.
When OctoRunMode=READONLY, Octopus operates in Read-Only mode. In this mode, only SELECT statements can be successfully executed; other SQL commands (such as CREATE..., ALTER..., INSERT, DELETE, or UPDATE) have no effect. This is the default setting.
When OctoRunMode=PRIVATEUPDATE, Octopus operates in Private Update mode: users are able to execute non-SELECT SQL commands that alter their private version of the database, and then work with this altered version within the same transaction. However, they cannot execute the COMMIT [WORK] command, and are forced to roll back any changes at the end of their session.
When OctoRunMode=PUBLICUPDATE, Octopus operates in Public Update mode. Non-SELECT SQL commands (and all subsequent commands in the same transaction) are sent to the OctoEng in the Updatable Subclass. It is also possible to connect and import data with the SAND CDBMS Data Loader (ndlm). When the COMMIT [WORK] command is successfully executed, Octopus automatically refreshes the database version used by all active OctoEng’s in the Octopus system. Database changes made while operating in Public Update mode can be permanently saved by executing the SET UPDATE KEEP CHANGE command.
When OctoRunMode=ODDB, Octopus will operate in On-Demand Database mode: when a client connects to Octopus in ODDB mode and references a database name other than the one defined for the Octopus instance, Octopus will look for the appropriate [DATABASE database-name] section in the nucleus.ini file. If found, an instance of that database will be started in Persistent Mode. If the specified database name matches the one defined for the Octopus instance, the instance will be started in Read-Only mode.
(On-Demand Database mode) The maximum amount of virtual memory (in megabytes) that will be allocated for database operations. If set in a DATABASE section, the setting applies to that database only. If set in the OCTOPUS section,the cache setting applies to all databases started as ODDB instances.
(On-Demand Database mode) The comma-separated list of databases that can be started as ODDB instances. If a user requests a database not in this list, an "access denied" error message will be returned.
Note that each database in the list should have a corresponding [DATABASE database-name] section in the nucleus.ini file.
Default: (all databases)
(On-Demand Database mode) The location of the Delta Files to which changes to the database will be written.
Default: . (current directory)
(On-Demand Database mode) Setting this parameter to TRUE keeps the ODDB instance running after the last client has disconnected from it. The amount of time that the ODDB instance will keep running without any active client connections is specified using the ODDBKeepAliveTimeOut parameter (which is 43,200 seconds12 hoursby default).
(On-Demand Database mode) The amount of time (in seconds) that an ODDB instance will keep running after the last client has disconnected from it, when the ODDBKeepAlive parameter is set to TRUE. Setting this to 0 or a negative number causes the ODDB instance to time out right away, which is the same as setting ODDBKeepAlive to FALSE.
Default: 43200 (equivalent to 12 hours)
(On-Demand Database mode) Sets the amount of detail that will be written to the log file for each new ODDB instance. By default, the amount of detail is at the highest level, so this parameter can only be used to reduce ODDB logging.
(On-Demand Database mode) The maximum amount of cache (in megabytes) that can be used by all ODDB instances running on this Octopus instance.
(On-Demand Database mode) The maximum number of ODDB instances that can run on this Octopus instance.
|ODDBMaxVMem=||(On-Demand Database mode) See the MaxVMem parameter description above.|
(On-Demand Database mode) The priority group to which this Octopus instance belongs. All ODDB instances requested on this configuration will belong to this group. Queued ODDB instance requests will be served by Octopus Agents according to the group priority order, specified by the Agent ODDBPriority parameter.
Note that the priority group name can be arbitrary.
Default: (unnamed or default group)
(On-Demand Database mode) Sets the public ODDB flag. If a database is designated as a public On-Demand Database, it will be included in a comma-delimited ODDB list returned by Octopus to programs (for instance, octoinfo) that request this information. This flag does not actually affect ODDB functionality; a non-public On-Demand Database can be started by Octopus, as long as the client provides the appropriate database name.
(On-Demand Database mode) Specifies the ODDB operation mode, which is either ReadOnly or Update. ODDB ReadOnly is the same as the standard Octopus ReadOnly mode: SQL statements that attempt to change the database will have no effect. In contrast, Update mode allows changes, and will also accept SHUTDOWN and KEEP CHANGE commands.
(On-Demand Database mode) Specifies whether an ODDB instance can be shared among multiple sessions of the same or different users. Setting this parameter to TRUE (the default) enables sharing. Setting this parameter to FALSE causes Octopus to start a separate ODDB instance for each session.
(On-Demand Database mode) Specifies whether the Subclass can be used to start ODDB instances. Only Subclasses that have this parameter set to TRUE will be used for ODDB operations.
Defaults: TRUE (if there is only one Subclass)
|PassEnv=||Specifies custom parameter(s)
that will be added to the end of the NUCLEUS environment variable for
the current Octopus session. Note that settings made in the NUCLEUS variable
override those made in the nucleus.ini file.
Parameters are defined in the following manner:
There are two ways that multiple parameters can be specified through PassEnv (and both methods can be combined).
The port on which Octopus will listen for connection requests from clients. The relevant CONNECTION section of the client-side nucleus.ini file must contain a matching Port specification.
To override the restriction, use the StartPort parameter described below.
The name of the core database that will be used (in a variant of Persistent mode) by the Octopus instance.
from the OCTOPUS section header
When all OctoEng's in the heaviest class are busy processing update transactions in Private Update mode, each will be exclusive to a specific session until that session has been idle for the duration specified by this parameter.
Once this period has elapsed, another session will be permitted to share that OctoEng with the original session.
Default: 60 seconds
Specifies the amount of time Octopus will allow an OctoEng to remain idle (after the last session activity) before being restarted with a new version of the database in response to an OctoRefresh command. When the OctoEng is restarted, any changes previously made in that session will be discarded.
Default: 900 seconds (15 minutes)
When set to TRUE in Public Update mode, Octopus will restart the master engine in recovery mode after an abnormal termination, which will allow a restart from the last successful COMMIT WORK.
(On-Demand Database mode) The amount of time (in seconds) before an SQL query executed against the On-Demand Database is cancelled. Specify 0 (or omit this parameter altogether) to remove all limits on the length of time a query may execute.
Note that setting this parameter has the same effect as issuing the SET TRANSACTION TIMEOUT SQL command. If both RescheduleTimeout and SET TRANSACTION TIMEOUT are set with differing values, the effective timeout period is the lower of the two.
When set to 0, Octopus does not enforce database user name/password verification when accepting connection requests from the OctoInfo, OctoKill, OctoRefresh, OctoRollLog, OctoShutdown and Sonar programs.
Default: 1 (user name/password verification is enforced)
Designates one or more database users as Session Admin. Session Admin users are able to view information about all active sessions and commands using the OctoInfo utility or the Sonar graphical interface, and to terminate any of these commands using the OctoKill program or Sonar. Multiple user names must be separated by commas.
No particular database privileges are required to be Session Admin. The specified user authorizations must already exist in the database.
Enables or disables client request sharing. When enabled (the default), if all OctoEng's across the classes of service are in use, the latest client request will be assigned to the least recently used OctoEng in the heaviest class, instead of being queued for assignment. That is, one or more OctoEng's in the heaviest class will take advantage of multithreading to process multiple client requests simultaneously, eliminating the need for request queues.
Note that the special Login class is supported even if request sharing is enabled.
Default: TRUE (enabled)
Integer representing the snapshot (Time Travel database version) to be used when starting the Octopus database.
Default: current snapshot
The amount of time (in seconds) to wait for a local OctoEng to start up before timing out. This value must be a nonnegative integer. A value of 0 disables the OctoEng timeout (unlimited wait).
Note that in a multi-Node system, this parameter (if used) must be configured in the [OCTOPUS AGENT] section of each Node’s nucleus.ini file.
Default: 0 (disabled)
|The base port number to be used
by Octopus when automatically starting OctoEng's. This parameter overrides
the restriction on port numbers for multiple Octopus instances, allowing
the difference between them to be less than 50. If this parameter is omitted,
the restriction is enforced.
name and location of the file to which detailed Octopus statistics are
specified by the DatabasePath parameter
period (in seconds) over which cumulative statistics will be compiled.
This value must be greater than 5.
See the Monitoring, Logging, and Statistics section for information about Octopus statistics.
If this parameter is not included, no statistics are
compiled by Octopus.
(On-Demand Database mode)
Forces OctoEng’s to automatically delete (TRUE) or retain (FALSE) the temporary Delta File.
Setting this parameter
to FALSE enables temporary updates via OctoEng's in any class other
than the Login class. The default setting (TRUE) permits temporary updates
only on OctoEng's in the the heaviest class.