You can dynamically change the number of engines in use by Adaptive Server with the dbcc engine command to take an engine offline or bring an engine online. This allows a System Administrator to reconfigure CPU resources as processing requirements fluctuate over time.
Two configuration parameters limit the number of engines available to the server:
max online engines – when the server is started, the number of engines specified by max online engines are started. The number of engines can never exceed max online engines.
min online engines – sets the minimum number of engines. When you take engines offline using dbcc engine, you cannot reduce the number of engines below the value set by min online engines.
Due to the operating system limit on the number of file descriptors per process, reducing the number of engines reduces the number of network connections that the server can have.
There is no way to migrate a network connection created for server-to-server remote procedure calls, for example, connections to Replication Server and XP Server, so you cannot take an engine offline that is managing one of these connections.
The syntax for dbcc engine is:
dbcc engine(offline , [enginenum] )
dbcc engine("online")
If enginenum is not specified, the highest-numbered engine is taken offline.
Depending on your operating system and the load on Adaptive Server, taking an engine offline can take several minutes. To complete the task of taking an engine offline, the following steps must be completed:
All outstanding I/Os for the engine must complete.
All tasks affiliated with the engine must be migrated to other engines.
Operating system and internal cleanup must de-allocate all structures.
If tasks cannot be migrated within approximately 5 minutes, the tasks are killed.
WARNING! If you use dbcc engine(offline) when CPU utilization is high on the server, Adaptive Server may not be able to migrate all tasks before the time limit expires.Tasks that cannot be migrated within the time limit are killed.
When a System Administrator issues a dbcc engine(offline) command, messages are sent to the error log. For example, these are the messages on Sun Solaris:
00:00000:00000:1999/04/08 15:09:01.13 kernel engine 5, os pid 19441 offline
dbcc engine(offline) returns immediately; you must monitor the error log or check the engine status in sysengines to know that the offline-engine task completes.
An engine with open network connections using Client Library cannot be taken offline. Attempting to offline the engine reports this message in the error log:
00:00000:00000:1999/04/08 15:30:42.47 kernel ueoffline: engine 3 has outstanding ct-lib connections and cannot be offlined.
If there are tasks that cannot be migrated to another engine within several minutes, the task is killed, and a message similar to this is sent to the error log:
00:00000:00000:1999/04/08 15:20:31.26 kernel Process 57 is killed due to engine offline.
Values in the status column of sysengines track the progress of dbcc engine commands:
online – indicates the engine is online.
in offline – indicates that dbcc engine(offline) has been run. The engine is still allocated to the server, but is in the process of having its tasks migrated to other engines.
in destroy – indicates that all tasks have successfully migrated off the engine, and that the server is waiting on the OS level task to deallocate the engine.
in create – indicates that an engine is in the process of being brought online.
The following command shows the engine number, status, number of tasks affinitied, and the time an engine was brought online:
select engine, status, affinitied, starttime from sysengines
engine status affinitied starttime ------ ------------ ----------- -------------------------- 0 online 12 Mar 5 1999 9:40PM 1 online 9 Mar 5 1999 9:41PM 2 online 12 Mar 5 1999 9:41PM 3 online 14 Mar 5 1999 9:51PM 4 online 8 Mar 5 1999 9:51PM 5 in offline 10 Mar 5 1999 9:51PM
If you are using logical process management to bind particular logins or applications to engine groups, use dbcc engine(offline) carefully. If you offline all engines for an engine group:
The login or application can run on any engine
An advisory message is sent to the connection logging in to the server
Since engine affinity is assigned when a client logs in, users who are already logged in are not migrated if the engines in the engine group are brought online again with dbcc engine("online").
To maintain the correct number of engines, monitor CPU usage with an operating system utility. See the configuration documentation for your platform for the appropriate utility for your operating system.
