Octopus Administrator's Guide
Octopus Operations

Dynamically Reconfiguring Subclasses

The number of OctoEng�s and/or the Cache size for an Octopus Subclass can be dynamically reconfigured using the OctoRefresh program. DBA privileges are required to execute the octorefresh command. A user name (along with password, if applicable) must be included in the program invocation, unless privilege checking has been disabled by including the SecurityLevel=0 parameter in the relevant [OCTOPUS instance-name] section of the nucleus.ini file. When privilege checking is disabled, all users are connected as the user DBA.

Syntax

octorefresh -s "subclass-name" [-e [+|-]NumberOfEngines-value] [-c [+|-]Cache-value] connection-name database-name user-name[/password]

The new NumberOfEngines value can be any positive integer, except in the case of the updatable Subclass, where it must always be 1. The new Cache value (specified in megabytes) can be any positive integer. Optionally, the plus or minus operators can be used to increase or decrease the current value(s) by the specified number of engines or megabytes.

Note that when the Subclass is defined on a remote node, the Subclass name includes the node name, for example:

octorefresh -s "NODE1 Heavy" -e +1 -c +500 cn1 dbtest dba/pw

If the NumberOfEngines or Cache value is changed for a non-updatable Subclass, the change will be applied after any current queries or fetches have finished execution. If the Cache value is changed for the updatable Subclass, the change will be effected when the SET UPDATE KEEP CHANGE command is executed (see above). Note that the new values are not permanent: if Octopus is restarted, it will revert to the Cache and NumberOfEngines values specified in the nucleus.ini file.

Important Note:
It is possible to shut down all OctoEng's in the system using the OctoRefresh program. However, if this is done, it will no longer be possible to execute any of the Octopus utilities (including OctoShutdown and OctoRefresh). Octopus will have to be killed and restarted in order to restore system operation. This situation can be avoided by configuring a Login class devoted to processing client connection requests, and not shutting down the OctoEng in the associated Subclass.

Example:

As an example scenario, assume that Octopus is running with the following configuration for daytime users:

Subclass	Engines	Cache
Light	3	300 MB
Heavy	4	1000 MB
Update	1	1000 MB

The following steps show how the octorefresh command can be used to reconfigure the system in order to devote increased resources to a KEEP CHANGE operation overnight, then restore the original settings.

1. Reduce the engine count to 2 for the Light Subclass.
   

octorefresh -s "Light" -e 2 cn1 dbtest DBA/pw

2. Increase the engine count for the Heavy Subclass to 5 (by adding one engine) and increase the Cache to 1500 MB (by adding 500 MB).

octorefresh -s "Heavy" -e +1 -c +500 cn1 dbtest DBA/pw

3. Prepare a new larger Cache (8000 MB) for the Update Subclass.
   

octorefresh -s "Update" -c 8000 cn1 dbtest DBA/pw

4. Prepare to execute the KEEP CHANGE (here DBA is given the ability to execute that command).

SQL> SET UPDATE EXCLUSIVE TO DBA;

5. Create a new snapshot reflecting the changes made during the day. Note that the new 8000 MB Cache size now becomes active for the Update Subclass.

SQL> SET UPDATE KEEP CHANGE;

6. Lock the Update Subclass for the user user1.

SQL> SET UPDATE EXCLUSIVE TO user1;

This is similar to setting Octopus to run in read-only mode for everyone other than user1. Other users attempting a DDL statement or trying to change their password will receive the message:

Octopus Error: Updates are disabled. The system is in maintenance mode

At this point user1 can use nisqlm, ndlm or another tool to make changes to the database. User1 will always connect to the updatable OctoEng.

7. Prepare to restore the original Cache size (1000 MB) for the Update Subclass.

octorefresh -s "Update" -c 1000 cn1 dbtest DBA/pw

8. Perform the KEEP CHANGE to save the changes. The Cache size will be changed back to 1000 MB once the KEEP CHANGE process is complete.

SQL> SET UPDATE KEEP CHANGE;

9. Restore the "daytime" settings for the Light Subclass.

octorefresh -s "Light" -e 3 cn1 dbtest DBA/pw

10. Restore the "daytime" settings for the Heavy Subclass.

octorefresh -s "Heavy" -e 4 -c 1000 cn1 dbtest DBA/pw