ABAP application server instances

What the shell scripts do

This information unit describes the tasks performed by the shell scripts.

start_as

• For the remote application server, the start_as script first checks if the remote host can be reached via ping. This is retried three times, while sleeping 10 seconds between attempts, so the total ping wait time is 30 seconds. After start_as can ping the host, it determines the type of the application server, which can be either AIX, Linux, or Windows. Then, it checks for an ABAP application server, whether the database server can be reached from there via R3trans. In case of an error, the shell script indicates the status by sending a message to the system console, and then ends. Otherwise, if no error occurs, it then checks whether the instance is already running by using the IBM® utility samsapctrl_asping (see section samsapctrl_asping in this information unit). If the instance is running, the shell script indicates the status by sending a message to the system console, and then ends.

  This step protects a running application server instance from unnecessary restarts. For example, in case of an intermittent communication error, check_as terminates and IBM Z System Automation issues the start_as command again. Based on the notification of the active state message, IBM Z System Automation now starts check_as again.

  Using this approach, IBM Z System Automation only has to monitor a single process, namely the one started by check_as.

• An AIX or Linux ABAP application server is started by invoking the following SAP standard scripts or commands:

  stopsap r3 <instance> <hostname>
  cleanipc <instnr> remove
  startsap r3 <instance> <hostname>

  The stopsap and cleanipc commands ensure that orphan processes or resources are cleaned up before a new startsap is performed. If the instance was shut down normally, the cleanipc and stopsap commands do nothing and end immediately.

• Finally, the script checks periodically until the application server instance is running and responding to samsapctrl_asping. You can configure the maximum number of periodical checks using parameter <maxretries>. If the first check is unsuccessful the script retries for 10 * <maxretries> seconds. Successful startup is indicated by sending a message to the system console.

  Example: With <maxretries> = 24, the script gives up after 240 seconds and returns a STARTUP FAILED message. If starting the Java™ application server takes longer in your environment, you must use a higher<maxretries> counter.

• An AIX or Linux Java application server is started by invoking the following SAP standard scripts or commands:

  stopsap j2ee <instance> <hostname>
  cleanipc <instnr> remove
  startsap j2ee <instance> <hostname>

• A Windows application server is started with following SAP standard executables:

  stopsap name=<SID> nr=<instance number> SAPDIAHOST=<hostname>
  startsap name=<SID> nr=<instance number> SAPDIAHOST=<hostname>

stop_as

• The ABAP application server is stopped by invoking the following script for AIX and Linux:

  stopsap r3 <instance> <hostname>

  For Windows, the ABAP application server is stopped by invoking the following SAP executable:

  stopsap name=<SID> nr=<instance number> SAPDIAHOST=<hostname>

check_as

• The health check of the application server is done by requesting health status information via the sapcontrol interface of the AS instance. The sapcontrol interface is periodically called by using the samsapctrl_asping utility (see section samsapctrl_asping in this information unit). The parameter <InstType> specifies, for which application server type the monitor is started. A value 0 starts an ABAP application server (AS) monitor and a value of 2 starts a Java AS monitor.

  A failure of samsapctrl_asping indicates that there is (or was) a problem with that instance. Therefore, the existence of the samsapctrl_asping process is used by System Automation to determine the status of the application server instance.

  The script creates a link to the samsapctrl_asping executable such as ./AS_ABAP_ping_<hostname>_<instance number> in the current directory for an ABAP application server, or ./AS_Java_ping_<hostname>_<instance number> in the current directory for a Java application server.

  In the SA z/OS policy for the respective resource application, edit the z/OS UNIX Control options. For correct monitoring via SA z/OS:

  • The z/OS UNIX path should be /bin/sh
  • The z/OS UNIX filter should be ./AS_ABAP_ping_<hostname>_<instance number> for an ABAP application server, or ./AS_Java_ping_<hostname>_<instance number> for a Java application server.

samsapctrl_asping

• This utility uses the SAP's sapcontrol interface of the application server instance to get its health status. The command-line parameters allow you to choose between different modes. It must be installed in the home directory of the <sid>adm user.
• The default option is that samsapctrl_asping ends after it gets a response from the sapcontrol call for the ABAP or Java application server instance. This is used in the start_as script to check whether an application server instance is up and running.
• Another option specifies that samsapctrl_asping continues to run and checks the status periodically (the default is 30 seconds) via sapcontrol calls. It only ends if sapcontrol indicates a bad health status of the application server. Additionally, if sapcontrol returns with a timeout after 30 seconds, for example because of a connection problem, sapsapctrl_asping performs up to two retries. If each retry ends with a timeout, sapsapctrl_asping ends after the third timeout. This mode is used in the check_as script to monitor an ABAP or Java application server instance.
• samsapctrl_asping uses a message file. This file has the name sapolicy.sap.map_USS. It must be installed in the same directory as the samsapctrl_asping script, namely in the home directory of the <sid>adm user.

Invoking remote execution

SSH is the only remote execution type for the start and stop scripts that are used to control remote application servers. OpenSSH is the implementation of a secure shell, which allows different methods of authentication. It is available as a Program Product for z/OS and as an Open Source product on most other platforms including Linux and AIX. Under Windows, the scripts have been tested using the Tectia SSH Client/Server product, version 6.4, from the SSH Communications Security company, as a sample SSH client/server implementation.

OpenSSH uses hardware support to generate random numbers. This requires ICSF and ICSF must be started with /dev/random support prior to starting OpenSSH. More information on this topic can be found in Using hardware support to generate random numbers.

In the start_as script, the remote execution command is run in background.

For more detailed information, refer to the following websites and documentation:

• https://www.openssh.com/
• z/OS OpenSSH User's Guide