SAP on IBM i: Killing your Instance Softly with STOPSAP

In general, you want your SAP instances to stay up. However, from time to time you need to stop them, usually for maintenance work, such as installing a new kernel patch. In the past, you would have informed your end users to disconnect at a certain time, and then you would have stopped the instance at that time. With increasing requirements for application availability around the clock, it has become more and more difficult to find a maintenance window when the instances can be stopped.

SAP and IBM have provided high availability features that allow keeping some instances up and running while others are stopped for maintenance. One use case is the “Rolling Kernel Switch” as described in SAP Note 953653, another use case is a high availability configuration that allows to switch the database from the primary node to a secondary node in order to perform maintenance on the primary node. Such a configuration can be established when using IBM Db2 Mirror for i as described in SAP Note 2808345. In both cases, you do not want to stop the affected instances abruptly, but you want to give active users and background processes some time to complete their work, while no new users can logon and no new background processes can be started on this instance. This approach is called soft shutdown. If you are using the SAP Microsoft Management Console (SAP MMC), you may be familiar with soft shutdown.. With SAP Note 2992443 and the associated ILE patch levels, a new parameter Soft shutdown time (SOFTTIME) has been introduced to enable soft shutdown through the STOPSAP command on IBM i as well.

Prerequisite for enjoying the benefits of a soft shutdown is to setup load balancing through logon groups with the help of SAP transaction SMLG. A comprehensive description of the definition of logon groups and load balancing can be found in this article at https://wiki.scn.sap.com/wiki/display/SI/ABAP+Logon+Group+based+Load+Balancing#content. Whenever a new user is logging on to an SAP application server, the message server is picking the target instance from the logon group. Typically, the instance with the lowest current utilization is chosen, but when a soft shutdown is in progress for an instance, that instance will not be offered to the new user.

The complete soft shutdown happens in multiple phases. After the load balancing function is aware of the shutdown, external logins will be disabled, the scheduler for background processes will be stopped and the instance will give long running tasks some time to complete. Finally, periodic tasks will be ended, listen ports will be closed, and work processes will be monitored until they are all idle before the instance is stopped. A detailed flow chart of the soft shutdown process can be found in the SAP Help Portal, e.g. under SAP NetWeaver 7.5 → tab Operate → Technical Operations for SAP NetWeaver → Administration of Application Server ABAP → Soft Shutdown of Application Server ABAP. For the different shutdown phases, you can specify timeout values through a variety of profile parameters that are documented in the same section of the online documentation, such as rdisp/shutdown/auto_logout or rdisp/shutdown/idle_wp_timeout.

To initiate a soft shutdown from the command line, you login as <SID>ADM and use the STOPSAP command with the new parameter Soft shutdown time (SOFTTIME). The default value is SOFTTIME(*HARD), which reflects the same behavior as in the past and causes an immediate shutdown of the instance(s). Alternatively, you can specify a timeout in seconds. With that, STOPSAP will attempt a soft shutdown and wait for the specified time. If the instance is not stopped completely after that time, a hard shutdown will be initiated for that instance. With the special value SOFTTIME(*SOFT), the STOPSAP procedure will wait indefinitely for the soft shutdown to complete. Since the soft shutdown related profile parameters (rdisp/shutdown/auto_logout, rdisp/shutdown/idle_wp_timeout and so on) will kick in eventually, this should not take forever, unless the timeouts through profile parameters have been disabled as well. When specifying a SOFTTIME value other than *HARD, you can only stop a single instance, not INSTANCE(*ALL), and you cannot end the instance subsystem. Note that the STOPSAP parameter Maximum wait time (WAITTIME) is not related to the soft shutdown but has a different function: It specifies, how long the STOPSAP command will wait for the (hard) shutdown to complete before moving on. If that time is exceeded, STOPSAP will process the next instance or return to the caller, but the shutdown of the previous instance will continue until that instance is stopped.

For more explanations of the STOPSAP command and the new parameter, see the help function of the command STOPSAP (function key F1) and SAP Note 2992443.