startServer command

startServer command

The startServer command reads the configuration file for the specified server process and starts that server process.

Use the startServer command to:

Start an application server.
Start a DMZ Secure Proxy Server for IBM WebSphere Application Server.
Start an administrative agent.
Start a job manager.

IBM recommends using the High Performance Extensible Logging (HPEL) log and trace infrastructure . We view HPEL log and trace information using the LogViewer .
(Windows) If we are running the product on a Windows Windows operating system, and you have the server running as a Windows operating system service, the startServer command will start the server and the associated Windows service.

You do not have to use a user name and password with the startServer command because this command launches a server process but does not invoke an MBean method.

We can use the administrative console to change the Java virtual machine Classpath setting or the environment entries settings for a server. However, before making these changes you should understand the following consequences of making these changes:
Issuing the startServer -script command creates a script with static values. When we change JVM parameters from the console, a new script needs to be generated to accommodate these changed JVM parameters.
When we run the startServer -script, the command generates a new script that has all the parameter values at the time the command is run. If we change the values of the parameters (or add a new parameters), the generated script does not have these new parameter values. These new values are passed to the newly generated script in a static manner, so any changes made after this script is created will require a new startServer -script to generate a new script with these updated values.
If we change the value of the Java virtual machine Classpath setting, then this new value overrides the value of the Classpath parameter in the launch command that is set, by default, in the script generated when the you issue the startServer -script command.
If we add a new environment entry on the Environment entries page or change the setting of an existing entry, then the new and changed values appear as parameters in the script generated when you issue the startServer -script command.
If one of the environment entries you add is called PATH, then the value specified for this entry overrides the value specified for the PATH variable that, by default, is set to WAS_PATH in the setUpCmdLine file. If the value of the PATH variable is overridden, the following message is sent to the file where your error messages are logged:
WSVR0009E: Error occured during startup. com.ibm.ws.exception.RuntimeError: 
java.lang.NoClassDefFoundError: com/ibm/ws/process/Win32ProcessGlue
gotcha
For more information about where to run this command, see the Use command line tool topic.

Syntax

The command syntax is one of the following:
startServer server [options]
where server is the name of the application server or the DMZ Secure Proxy Server for IBM WAS that you want to start.

This argument is required.

(iSeries) This argument is optional. If this argument is not specified, a server is assigned based on your profile name. If we use the profile named default, the <server> argument is set to server1. If the profile name is not default, the <server> argument is set to the profile name.
startServer <adminagent_name>
whereadminagent_name is the name of the administrative agent that you want to start.
startServer <job_manager>
where job_manager is the name of job manager that you want to start.

Parameters

The following options are available for the startServer command:
-?

Prints a usage statement.

(iSeries) -curlib <product_library>

(iSeries) Current library to use for the underlying Submit Job (SBMJOB) CL command.

(iSeries) -cpyenvvar

(iSeries) Tells the startServer command to set the environment variables that are currently defined for the server process. The default is to not set the currently defined environment variables.

-help

Prints a usage statement.

(iSeries) -inllibl <library_list>

(iSeries) Specifies the initial library list to use for the underlying Submit Job (SBMJOB) CL command.

(iSeries) -inlaspgrp <ASP_group>

(iSeries) Specifies the initial ASP group for the underlying Submit Job (SBMJOB) CL command.

-J <java_option>

Specifies options to pass through to the Java interpreter.

(iSeries) -jobd <product_library/job_description>

(iSeries) Specifies the job description for the underlying Submit Job (SBMJOB) CL command.

(iSeries) -jobq <product_library/job_queue>

(iSeries) Specifies the job queue for the underlying Submit Job (SBMJOB) CL command.

-logfile <fileName>

Specifies the location of the log file to which trace information is written. By default, the log file is named startServer.log and is created in your logs directory.

-nowait

Tells the startServer command not to wait for successful initialization of the launched server process.

(iSeries) -outq <product_library/output_queue>

(iSeries) Specifies the output queue for the underlying Submit Job (SBMJOB) CL command.

-profileName

Defines the profile of the server process in a multi-profile installation. The -profileName option is not required for running in a single profile environment. The default for this option is the default profile.

-quiet

Suppresses the progress information that the startServer command prints in normal mode.

-replacelog

Replaces the log file instead of appending to the current log.

-recovery
Specifies that the server will start in recovery mode, perform a transactional recovery, and shut down. The server will not accept any new transactions while it is in recovery mode. When we start the server again, resources that were unavailable due to questionable transactions will be available.
Use this option if a server fails and we do not want to accept new transactions during the recovery process.

For transitioning users: If we are migrating from a previous version of the product, make sure that the ENV parameter included on the JCL procedure statement for the controller includes either the REC=N or the REC=Y element. If the ENV parameter does not include either the REC=N or the REC=Y element, the server will not restart in recovery mode even if you specify the -recovery option.
(ZOS) If the ENV parameter includes the REC=N element, the setting is automatically changed to REC=Y if you specify -recovery when restarting the server. The REC=N element is automatically included on the ENV parameter if you did not migrate from a previous version of the product. Following is an example of what your updated PROC statement might look like:
//BBO6ACR  PROC ENV=,PARMS=' ',REC=N,Z=BBO6ACRZ
trns
(iSeries) When we invoke the startServer command with the -recovery parameter and the recovery process is unsuccessful, the following error message occurs in the SystemErr.log and SystemOut.log files:
CWNATV03I: Application server xxxxxx in profile xxxxxx has completed recovery. Server stopped.
The message does not indicate that the recovery process was unsuccessful. If we use the -recovery parameter, check the SystemErr.log and SystemOut.log files for the server that we are starting to determine if the recovery process was successful.
(iSeries) -sbs <product_library/subsystem_description>

(iSeries) Subsystem to use for the underlying Submit Job (SBMJOB) CL command.

-statusport <portNumber>

An optional parameter that allows an administrator to set the port number for server status callback. The tool opens this port and waits for status callback from the server indicating that the server has started. If the parameter is not set, an unused port is automatically allocated.

-script [<script fileName>] -background

Generates a launch script with the startServer command instead of launching the server process directly. The launch script name is an optional argument. If we do not supply the launch script name, the default script file name is start_server based on the server name that is passed as the first argument to the startServer command. The -background parameter is an optional parameter that specifies that the generated script will run in the background when you run it.

-trace

Generates trace information to the log file for debugging purposes.

(iSeries) Enables tracing of the native process code that starts the server. The trace output is written to the was_jobname-jobuser-jobnum.log file which is located in the profile_root/logs directory.

-timeout <seconds>

Specifies the waiting time before server initialization times out and returns an error.

(iSeries) -usejobd

(iSeries) Specifies to use the job description from the Submit Job (SBMJOB) process for the server when switching to the Run-As user ID.
This command does not affect the USER field of the current job description.
Usage scenario

The following examples demonstrate correct syntax. The information within the parentheses is a description of the output created if you issue the preceding command.

(Dist)
startServer server1

startServer server1 -script (produces the start_server1.sh or .bat files)

startServer server1 -trace (produces the startserver.log file)

startServer adminagent

startServer.sh server1 -trace -username MyUserName -password MyUserPassword
 -profileName MyProfileName     (starts the server1 server using the 
         MyProfileName profile. The server runs under the user name MyUserName,
         and produces trace files under the profile_root/logs directory)
startServer jobmgr

startServer proxy1 (for the secure proxy profile)
(ZOS)
startServer server1

startServer server1 -script (produces the start_server1.sh file)

startServer server1 -trace (produces the startserver.log file)

startServer adminagent

startServer jobmgr

startServer proxy1 (for the secure proxy profile)

startServer.sh server1 -trace -username MyUserName -password MyUserPassword
 -profileName MyProfileName     (starts the server1 server using the 
         MyProfileName profile. The server runs under the user name MyUserName,
         and produces trace files under the profile_root/logs directory)
(iSeries)
startServer server1 (starts the server1 server for the default profile)

startServer server1 -trace (starts the server1 server for
the default profile and produces trace files under the profile_root/logs directory)

startServer -profileName mytest (starts server mytest 
configured under profile mytest)

startServer AdminAgent01
startServer JobMgr01

startServer proxy1 (default server name for the SecureProxySrv01 profile)
startServer.sh server1 -trace -username MyUserName -password MyUserPassword
 -profileName MyProfileName     (starts the server1 server using the 
         MyProfileName profile. The server runs under the user name MyUserName,
         and produces trace files under the profile_root/logs directory)
Exit codes

How do you capture the startServer and stopServer return code to determine if this was successful or not? This table shows the return codes for a server given a start or stop command.

The following example is a script executing and capturing the return code for server1:
#!/bin/sh
exitCode=`./startServer.sh server1`
The exitCode value can be compared to the following list of return codes to determine the results of the command:

Server state Return code
Server initialization failed -1
Server initialization timed out -2
Server start in progress 1
Server is initializing the applications that are present 2
Server initialization is complete (successful) 0
Server stop failed -10
Server stop timed out -11
Server stop operation started 1000
Server successfully stopped 0

Use command-line tools

Server state	Return code
Server initialization failed	-1
Server initialization timed out	-2
Server start in progress	1
Server is initializing the applications that are present	2
Server initialization is complete (successful)	0
Server stop failed	-10
Server stop timed out	-11
Server stop operation started	1000
Server successfully stopped	0