Web Application Server 6.40
SAPTelnetScript is a Java program that allows you to run batch scripts against the SAP J2EE TELNET interface. This can drastically shorten the time needed for certain low-level operations and provide a means to run scheduled jobs, such as the restart of J2EE applications, by combining it with crontab or other job scheduling tools.
Several example scripts are included in the associated download.
Applies to any SAP J2EE system providing the TELNET administration tool (Telnet Provider Service). Tested on SAP J2EE 6.40 SP13 and SAP J2EE 7.00 SP04.
11 Apr 2006
SAPTelnetScript is a Java program that allows you to run batch jobs against the TELNET interface of the SAP J2EE Engine. The TELNET interface of SAP J2EE provides low-level access to various administrative functions, some of which overlap with the functionality in Visual Administrator, and some of which are exclusive to the TELNET interface.
Normally when working with the TELNET interface you logon using a TELNET client (which is provided with most operating systems) and issue the commands needed. The image below shows a TELNET session made against J2EE Engine 6.40 from the standard Windows TELNET client. The TELNET client was started by running the command: "Telnet localhost 50008" from a command prompt.
Running the Program
In order to run the SAPTelnetScript program you will have to perform the following tasks:
Unzip the distribution file above.
Create an options properties file.
Create a command file.
Start the Java program.
Options Property File
The options property file specifies which SAP J2EE to connect, what user to use and some other options for the program. The file uses the standard Java Properties format, which in essence is a file consisting of key-value pairs.
The possible options in this file are:
ServerHostName: The host name or ip-address of the SAP J2EE to contact.
TelnetPort: The port SAP J2EE TELNET is running on (usually 50008).
Username: The username to connect with. Must be a member of the administrators groups in SAP J2EE. Please do not use the default administrator (see Advanced topic Locked administrator).
Password: The password of the user.
OperationTimeoutMS (optional): How long each TELNET command is allowed to execute for.
Note that the TelnetPort for an SAP J2EE engine is 50000+100*instance_number+8, if not otherwise specified in the Telnet Provider Service.
The "#" character can be used for comments in the options property file.
A typical file will be:
#Script for restarting the irj application
#jump to server node
#add deploy command group
#stop the application synchronously
STOP_APP irj –synchron
#start the application
START_APP irj –synchron
The command file is a standard text file in which the commands are separated by a new line. Blank lines or lines starting with # or // will be treated as comments and not processed.
The commands should be valid SAP TELNET commands, but no check is done by SAPTelnetScript to ensure this. It is not necessary to enter a command to quit the session as this is done automatically by SAPTelnetScript.
You can find an overview of various TELNET commands on the Shell Administration Commands page of SAP Help Portal.
Example command files included in the distribution are:
cmdRestartIRJ.txt - Restarts the irj (SAP EP) application.
cmdDeployEAR.txt - Deploys an EAR file to SAP J2EE. Script must be customized before usage(see comments in script). Be aware that direct deployment via this script bypasses SDM and therefore shouldn't be done in production system.
cmdClearHTTPCache - Clears the HTTP cache.
cmdListHTTPSessions - Lists the current HTTP sessions.
cmdRestartJMS.txt - Restart the JMS provider service.
cmdRunGC.txt - Runs the garbage collector.
cmdSystemInfo.txt - Prints out some system information like used memory and number of threads.
Starting the SAPTelnetScript Java Program
SAPTelnetScript is distributed as a standard Java jar file along with some example options and command files. To run the Java program with the options file sapTelnet.properties and command file cmdRestartIRJ.txt do the following:
If Java is not installed do this first and follow the SUN's procedure for setting up JAVA_HOME and CLASSPATH environment variables. The program has been tested with Java 1.42.
Open a command prompt to the folder you've downloaded SAPTelnetScript.
If not already there, place the options file (sapTelnet.properties) and command file (cmdRestartIRJ.txt) in the same folder.
Run Java –jar sapTelnetScript.jar sapTelnet.properties cmdRestartIRJ.txt.
All TELNET session are non-encrypted and this program is no exception. This means that you are sending the username and password of the TELNET user in clear-text over the network. Make sure no-one has the possibility to sniff this traffic. This can be done by setting a firewall around the environment that blocks the TELNET port for external access. If this is done, the SAPTelnetScript must be run from inside the firewall (same location as the SAP J2EE servers).
The username and password the program connects with is stored in the properties file. Make sure that the file-rights of this file only allow read rights to the user running the SAPTelnetScript.
It is very easy to lock the administrator with the default settings (believe me, I’ve done it a few times). If this happens, you need to activate sap*, restart on the SAP J2EE, unlock administrator, deactivate sap*, and restart SAP J2EE. (See Activating the Emergency User.) It is therefore strongly recommended to create a separate user that is used by SAPTelnetScript. This user needs to be member of the administrators groups. Select that the user need not change password, otherwise the script will hang when a password change is required.
Although SAPTelnetScript doesn’t provide direct support for scheduled jobs, it should be easy to use another tool scheduling a regular job. For UNIX/LINUX you can use crontab and for Windows you can use the Windows Scheduled Tasks. You can also use a pure Java framework such as Quartz.
If you need to provide behavior based on the output of the TELNET script, the suggested method is to subclass SAPTelnetScript and reimplement the methods void postProcessResult(String command,String output) and String nextCommand()throws IOException . The postProcessResult method is called after each TELNET command has finished and can be used to parse the results. The SAPTelnetScript implementation of this method prints the output to System.out. The nextCommand method is called by the script in order to get the next command to send to the TELNET session. The SAPTelnetScript implementation of this method reads the next non-comment line from the command file.
Command Groups in SAP J2EE Telnet
By default when you connect to SAP J2EE you have access to the ADMIN, SYSTEM, and TELNET command groups. You can see a list of the currently available commands by typing the command MAN. If you would like to learn more of a command in this list, type MAN <command name>.
You can add new command groups to the TELNET session by typing ADD <command group name>, for example ADD HTTP. Note that some command groups are only for dispatcher nodes, whilst others are for server nodes. Shell Administration Commands lists the available command groups for both dispatcher and server node.
The jump command allows you to change the active node in the TELNET session. It is defined by SAP as:
Usage: JUMP <clusterId> - Connects the terminal to the specified node's shell. If 'clusterId' is between 0 and 9, jump to the first cluster node whose id ends with 'clusterId' .
In order to connect to an application server node once you have connected a TELNET session, use the command JUMP 0. If the JUMP 0 command is issued twice, you change back to the original dispatcher node.
The following error return codes are used by the program:
-1: Initialize failed
-2: Not initialized (run method called before init, should not happen)
-3: Invalid login to SAP J2EE
-4: Connection failed to SAP J2EE. J2EE down, wrong connection properties or firewall blocking access
-5: A timeout of one of the commands
-9: A general TELNET exception (possibly called if the J2EE closes the connection)
Character Encoding in the Command File
I've experienced that when copying data from Microsoft Office to a text file in NWDS, that the some characters are not properly read by Java and replaced with "?" characters. If this happens, open the command file in a text editor (textedit or notepad) and correct it here.